Webhooks

Events, the content of a message, verifying the signature, retries and duplicate messages.

Last updated: Need help? Contact support

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#

EventWhen
shipment.status_changedThe status of a shipment (trip) changes.
invoice.finalizedAn invoice or credit note becomes final.
invoice.paidA final invoice is marked as paid.
pingA 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.

  1. Read t and v1 from the header.
  2. Compute HMAC-SHA256 over t + "." + raw body with your secret.
  3. Compare with v1 using a constant-time comparison.
  4. Reject the message if t is 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 2xx status. 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.