Webhooks
Gebeurtenissen, de inhoud van een bericht, de handtekening controleren, nieuwe pogingen en dubbele berichten.
Met een webhook stuurt INTEGALL een POST-bericht naar uw adres zodra er iets gebeurt. Het transportbedrijf stelt webhooks in in het bedrijfspaneel (API-sleutels en webhooks) en geeft u het ondertekeningsgeheim (whsec_…), dat maar één keer getoond wordt.
Gebeurtenissen#
| Gebeurtenis | Wanneer |
|---|---|
shipment.status_changed | De status van een zending (rit) wijzigt. |
invoice.finalized | Een factuur of creditnota wordt definitief. |
invoice.paid | Een definitieve factuur wordt als betaald gemarkeerd. |
ping | Een testbericht vanuit het paneel (Testbericht sturen). |
Voorbeeldgegevens uit het paneel sturen nooit een webhook.
Het bericht#
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"
}
}Bij invoice.finalized en invoice.paid staat er in plaats van shipment een object invoice met id, number, type, customer_id, issue_date, due_date, net en paid_date. Bij ping staat er "test": true.
De handtekening controleren#
De header X-INTEGALL-Signature heeft de vorm t=<unix-seconden>,v1=<handtekening>. De handtekening is de HMAC-SHA256 (hexadecimaal) van de tekst <t>.<ruwe body> met uw whsec_-geheim.
- Lees
tenv1uit de header. - Bereken HMAC-SHA256 over
t + "." + ruwe bodymet uw geheim. - Vergelijk met
v1met een vergelijking in constante tijd. - Weiger het bericht als
touder is dan 5 minuten.
Voorbeeld 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)Gebruik de ruwe body zoals ontvangen, niet een opnieuw opgemaakte JSON.
Antwoorden en nieuwe pogingen#
- Antwoord binnen 10 seconden met een status
2xx. Verwerk zware taken daarna, niet tijdens het antwoord. - Doorverwijzingen (
3xx) worden niet gevolgd en tellen als mislukt. - Een mislukte bezorging wordt opnieuw geprobeerd na 1, 5 en 15 minuten, 1, 3, 8 en 16 uur: 8 pogingen, ongeveer 28 uur.
- Een bericht dat na alle pogingen niet aankwam, kan het bedrijf in het paneel opnieuw laten versturen (Mislukte opnieuw versturen, de laatste 7 dagen).
- Antwoordt uw adres meer dan 24 uur onafgebroken niet, dan wordt de webhook automatisch uitgezet.
Dubbele berichten#
Een bericht kan meer dan eens aankomen. Gebruik het veld id van de body (ook in X-INTEGALL-Delivery) om dubbele berichten te herkennen en maar één keer te verwerken.
Vereisten voor uw adres#
- Enkel
https, op poort 443, zonder gebruikersnaam of wachtwoord in het adres. - Een publieke domeinnaam, geen IP-adres. Adressen die naar een intern netwerk wijzen, worden geweigerd.
- Hoogstens 10 webhooks per bedrijf.