Webhooks
When something changes in an organization that installed your app (a new order, a delivered shipment), the app receives a POST at its webhook URL. Deliveries follow the Standard Webhooks specification.
The URL and the events are picked in the partner portal, on the app's Webhooks tab. They are not versioned: a change applies at once, with no review. They apply to every installation of the app, but an installation receives only the events its scopes can read: without read_orders, no order.*.
The URL is https (http only for localhost). Replacing or clearing a saved URL asks for the password; the first URL is saved without it.
Public and private apps receive webhooks alike, for each of their installations.
Events
Section titled "Events"| Event | When | Resource in the payload |
|---|---|---|
order.created |
A new order arrived. Its status is still checking: an order.updated follows once it is checked. |
the order |
order.updated |
Something the order shows changed: its data, its status, its issues, its delivery service or its printed_at. Never sent when nothing you can see changed. |
the order |
shipment.created |
A shipment was created, pending (the same moment POST /shipments answers 202). |
the shipment |
shipment.status_changed |
A shipment took another status: the courier's answer (created with its AWB, failed, needs_attention), asked again after a refusal, a tracking move, cancelled. |
the shipment |
shipment.cancelled |
A shipment was cancelled, or set aside without an AWB. A shipment.status_changed is sent too. |
the shipment |
invoice.created |
An invoice (or a storno, kind storno) was created, pending (the same moment POST /invoices answers 202). |
the invoice |
invoice.status_changed |
An invoice took another status: issued, failed, needs_attention, asked again, cancelled, discarded, reversed (its storno issued). |
the invoice |
app.uninstalled |
The installation ended: the merchant uninstalled the app, the organization was deleted, the app was deleted or its retirement completed (uninstalling). Not picked from the list: always sent. | |
webhook.test |
The "Send a test event" button on the Webhooks tab. Not picked from the list. organization is null. |
Payload
Section titled "Payload"The body is JSON, in the shape Standard Webhooks recommends:
type: the event (order.updated);timestamp: when the event happened, RFC 3339 in UTC with six fractional digits, like a resource's moments (the same on every retry);organization: the public identifier of the organization the event happened in (org_...), the oneGET https://api.connectato.com/v1/organizationanswers with the installation's token: that is how you tell which installation a delivery belongs to. It isnullforwebhook.test, which comes from no organization;data: the whole resource, in its v1 shape (the same asGETreturns); an empty object forapp.uninstalledandwebhook.test.
{ "type": "order.created", "timestamp": "2026-11-13T09:30:00.123456Z", "organization": "org_01jcq2b8h4n6r0t5v9x3z7k1mp", "data": { "id": "ord_01jcq4m5x2v7k9t3r8n6p0w1yz", "updated_at": "2026-11-13T09:30:00.123456Z" }}The event's identifier is the webhook-id header. The body is built once, when the event happens: a retry sends exactly the same bytes, with the resource as it was then.
The resource carries updated_at. Deliveries can arrive in another order than the events happened (a retry can land after a newer event): keep the version with the newest updated_at. New fields may appear at any time: ignore the ones you do not know.
Headers
Section titled "Headers"| Header | Content |
|---|---|
webhook-id |
The delivery's identifier (msg_...); the same on every retry and on a resend. |
webhook-timestamp |
When this attempt was made, in Unix seconds. |
webhook-signature |
One or more signatures, separated by spaces, each in the form v1,<base64 signature>. One is sent today. |
Verifying the signature
Section titled "Verifying the signature"Every app has a signing secret starting with whsec_. The signature is an HMAC-SHA256:
- The HMAC key is the secret without the
whsec_prefix, base64-decoded. - The signed content is
webhook-id,webhook-timestampand the body, joined by dots:{webhook-id}.{webhook-timestamp}.{body}. - The result, base64-encoded, is compared with each
v1,...value inwebhook-signature, in constant time. One match is enough. webhook-timestampmust be close to the current time (for example, within 5 minutes), so an old delivery cannot be replayed by someone else.
<?php
function verifyWebhook(string $payload, array $headers, string $secret, int $tolerance = 300): bool{ $headers = array_change_key_case($headers, CASE_LOWER); $id = $headers['webhook-id'] ?? ''; $timestamp = $headers['webhook-timestamp'] ?? ''; $signatures = $headers['webhook-signature'] ?? '';
if ($id === '' || $signatures === '' || ! ctype_digit($timestamp)) { return false; }
if (abs(time() - (int) $timestamp) > $tolerance) { return false; }
$key = base64_decode(str_starts_with($secret, 'whsec_') ? substr($secret, 6) : $secret); $expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$payload}", $key, true));
foreach (explode(' ', $signatures) as $signature) { [$version, $value] = array_pad(explode(',', $signature, 2), 2, '');
if ($version === 'v1' && hash_equals($expected, $value)) { return true; } }
return false;}
// The raw body, exactly as received (in Laravel: $request->getContent()).$payload = file_get_contents('php://input');
if (! verifyWebhook($payload, getallheaders(), getenv('WEBHOOK_SECRET'))) { http_response_code(401); exit;}import crypto from 'node:crypto';import express from 'express';
export function verifyWebhook(payload, headers, secret, toleranceSeconds = 300) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signatures = headers['webhook-signature'];
if (!id || !signatures || !/^\d+$/.test(timestamp ?? '')) { return false; }
if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > toleranceSeconds) { return false; }
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64'); const expected = crypto .createHmac('sha256', key) .update(`${id}.${timestamp}.`) .update(payload) .digest();
return signatures.split(' ').some((signature) => { const [version, value] = signature.split(',', 2); if (version !== 'v1' || !value) { return false; } const received = Buffer.from(value, 'base64'); return received.length === expected.length && crypto.timingSafeEqual(received, expected); });}
const app = express();
// express.raw keeps the raw body (a Buffer), exactly as received.app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => { if (!verifyWebhook(req.body, req.headers, process.env.WEBHOOK_SECRET)) { return res.sendStatus(401); }
const event = JSON.parse(req.body); // Queue the event and answer at once. res.sendStatus(204);});import base64import hashlibimport hmacimport time
def verify_webhook(payload: bytes, headers: dict, secret: str, tolerance: int = 300) -> bool: headers = {key.lower(): value for key, value in headers.items()} msg_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp", "") signatures = headers.get("webhook-signature")
if not msg_id or not signatures or not timestamp.isdigit(): return False
if abs(time.time() - int(timestamp)) > tolerance: return False
key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + payload expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
for signature in signatures.split(" "): version, _, value = signature.partition(",") if version == "v1" and hmac.compare_digest(value, expected): return True
return False
# Flask: request.get_data() returns the raw body, exactly as received.# verify_webhook(request.get_data(), dict(request.headers), os.environ["WEBHOOK_SECRET"])The Standard Webhooks reference libraries (PHP, JavaScript, Python and more, listed on standardwebhooks.com) run the same verification.
Uninstalling
Section titled "Uninstalling"app.uninstalled announces that the installation ended: its tokens are already revoked, and requests with them get a 401. It is not picked from the list of events: it always reaches any app that receives webhooks (a saved URL, deliveries not stopped, the app not suspended), even when the installation's scopes cover no resource.
organizationnames the installation that ended;datais an empty object.- That merchant's data received through the API is deleted within 30 days, except what the law or your contract with the merchant obliges you to keep (Partner agreement).
- The merchant may install the app again at any time; the new installation gets new tokens, through OAuth.
Response and retries
Section titled "Response and retries"- Answer with a
2xxstatus within 10 seconds. Any other status, a timeout or a connection error is a failed delivery. Redirects (3xx) are not followed. - The URL must be public: an address resolving into a private network, to loopback or to a link-local address is never called.
- Answer at once and process the event in the background (a queue), so you never run out of time.
- A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours. After the last attempt the delivery stays failed and the partner's contact address gets an email.
- A
429or503answer with aRetry-Afterheader (seconds or an HTTP date) holds the next attempt until then, when that is later than the schedule's, by at most 10 hours. - A
410 Goneanswer means the URL takes no more events: the delivery fails at once and the URL is disabled at once, as after 3 days of failures. - A URL where every delivery fails for 3 days is disabled until you turn it back on from the Webhooks tab. While it is disabled, no event is sent.
- Deliveries (event, attempts, status, duration, next attempt, the body sent) are visible on the Webhooks tab for 30 days, with a manual resend. The email about a failed delivery is sent at most once a day per app.
- The signing secret is made when the URL is first saved and shown once. It is replaced with Rotate secret, with the password confirmed; after a rotation, every delivery is signed with the new secret.
The same delivery can arrive more than once (a retry after a lost response). Use webhook-id to process each delivery only once.