Webhooks
Ereignisse, der Inhalt einer Nachricht, die Signatur prüfen, erneute Zustellversuche und doppelte Nachrichten.
Mit einem Webhook sendet INTEGALL eine POST-Nachricht an Ihre Adresse, sobald etwas geschieht. Das Transportunternehmen richtet Webhooks im Unternehmensbereich ein (API-Schlüssel und Webhooks) und gibt Ihnen das Signaturgeheimnis (whsec_…), das nur ein einziges Mal angezeigt wird.
Ereignisse#
| Ereignis | Wann |
|---|---|
shipment.status_changed | Der Status einer Sendung (Fahrt) ändert sich. |
invoice.finalized | Eine Rechnung oder Gutschrift wird endgültig. |
invoice.paid | Eine endgültige Rechnung wird als bezahlt markiert. |
ping | Eine Testnachricht aus dem Unternehmensbereich (Testnachricht senden). |
Beispieldaten aus dem Unternehmensbereich lösen nie einen Webhook aus.
Die Nachricht#
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"
}
}Bei invoice.finalized und invoice.paid steht statt shipment ein Objekt invoice mit id, number, type, customer_id, issue_date, due_date, net und paid_date. Bei ping steht "test": true darin.
Die Signatur prüfen#
Der Header X-INTEGALL-Signature hat die Form t=<unix-sekunden>,v1=<signatur>. Die Signatur ist der HMAC-SHA256 (hexadezimal) des Textes <t>.<roher Body> mit Ihrem whsec_-Geheimnis.
- Lesen Sie
tundv1aus dem Header. - Berechnen Sie HMAC-SHA256 über
t + "." + roher Bodymit Ihrem Geheimnis. - Vergleichen Sie das Ergebnis mit
v1, mit einem Vergleich in konstanter Zeit. - Weisen Sie die Nachricht zurück, wenn
tälter als 5 Minuten ist.
Beispiel 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)Verwenden Sie den rohen Body so, wie er empfangen wurde, nicht ein neu formatiertes JSON.
Antworten und erneute Zustellversuche#
- Antworten Sie innerhalb von 10 Sekunden mit einem Status
2xx. Verarbeiten Sie aufwendige Aufgaben danach, nicht während der Antwort. - Weiterleitungen (
3xx) werden nicht verfolgt und gelten als fehlgeschlagen. - Eine fehlgeschlagene Zustellung wird nach 1, 5 und 15 Minuten sowie nach 1, 3, 8 und 16 Stunden erneut versucht: 8 Versuche, etwa 28 Stunden.
- Eine Nachricht, die nach allen Versuchen nicht angekommen ist, kann das Unternehmen im Unternehmensbereich erneut senden lassen (Fehlgeschlagene erneut senden, die letzten 7 Tage).
- Antwortet Ihre Adresse mehr als 24 Stunden ununterbrochen nicht, wird der Webhook automatisch ausgeschaltet.
Doppelte Nachrichten#
Eine Nachricht kann mehr als einmal ankommen. Verwenden Sie das Feld id im Body (auch in X-INTEGALL-Delivery), um doppelte Nachrichten zu erkennen und nur einmal zu verarbeiten.
Anforderungen an Ihre Adresse#
- Nur
https, auf Port 443, ohne Benutzername oder Passwort in der Adresse. - Ein öffentlicher Domainname, keine IP-Adresse. Adressen, die auf ein internes Netz zeigen, werden abgelehnt.
- Höchstens 10 Webhooks pro Unternehmen.