Webhooks

Gebeurtenissen, de inhoud van een bericht, de handtekening controleren, nieuwe pogingen en dubbele berichten.

Laatst bijgewerkt: Hulp nodig? Contacteer support

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#

GebeurtenisWanneer
shipment.status_changedDe status van een zending (rit) wijzigt.
invoice.finalizedEen factuur of creditnota wordt definitief.
invoice.paidEen definitieve factuur wordt als betaald gemarkeerd.
pingEen 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.

  1. Lees t en v1 uit de header.
  2. Bereken HMAC-SHA256 over t + "." + ruwe body met uw geheim.
  3. Vergelijk met v1 met een vergelijking in constante tijd.
  4. Weiger het bericht als t ouder 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.