Webhooks
Events, the content of a message, verifying the signature, retries and duplicate messages.
With a webhook INTEGALL sends a POST message to your address as soon as something happens. The transport company sets up webhooks in the company panel (API keys and webhooks) and gives you the signing secret (whsec_…), which is shown only once.
Events#
| Event | When |
|---|---|
shipment.status_changed | The status of a shipment (trip) changes. |
invoice.finalized | An invoice or credit note becomes final. |
invoice.paid | A final invoice is marked as paid. |
ping | A test message from the panel (Send test message). |
Sample data from the panel never sends a webhook.
The message#
POST /integall HTTP/1.1
Content-Type: application/json
User-Agent: INTEGALL-Webhooks/1.0
X-INTEGALL-Event: shipment.status_changed
X-INTEGALL-Delivery: 1042
X-INTEGALL-Signature: t=1795000000,v1=5f2b…{
"id": 1042,
"event": "shipment.status_changed",
"at": "2026-11-18T09:05:00Z",
"shipment": {
"id": "ex-0001",
"ref": "RR-26-0003",
"from_status": "loading",
"status": "transit",
"changed_at": "2026-11-18T09:05:00Z"
}
}With invoice.finalized and invoice.paid there is an invoice object instead of shipment, with id, number, type, customer_id, issue_date, due_date, net and paid_date. With ping there is "test": true.
Verifying the signature#
The X-INTEGALL-Signature header has the form t=<unix-seconds>,v1=<signature>. The signature is the HMAC-SHA256 (hexadecimal) of the text <t>.<raw body> with your whsec_ secret.
- Read
tandv1from the header. - Compute HMAC-SHA256 over
t + "." + raw bodywith your secret. - Compare with
v1using a constant-time comparison. - Reject the message if
tis older than 5 minutes.
Example in Python:
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t, sig = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig)Use the raw body as received, not re-serialised JSON.
Responses and retries#
- Respond within 10 seconds with a
2xxstatus. Do heavy work afterwards, not during the response. - Redirects (
3xx) are not followed and count as failed. - A failed delivery is retried after 1, 5 and 15 minutes, and 1, 3, 8 and 16 hours: 8 attempts, about 28 hours.
- A message that did not arrive after all attempts can be resent by the company in the panel (Resend failed, the last 7 days).
- If your address does not respond for more than 24 hours without interruption, the webhook is turned off automatically.
Duplicate messages#
A message can arrive more than once. Use the id field of the body (also in X-INTEGALL-Delivery) to recognise duplicates and process them only once.
Requirements for your address#
- Only
https, on port 443, without user name or password in the address. - A public domain name, not an IP address. Addresses pointing to an internal network are refused.
- At most 10 webhooks per company.