Webhooks

Ereignisse, der Inhalt einer Nachricht, die Signatur prüfen, erneute Zustellversuche und doppelte Nachrichten.

Zuletzt aktualisiert: Hilfe nötig? Support kontaktieren

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#

EreignisWann
shipment.status_changedDer Status einer Sendung (Fahrt) ändert sich.
invoice.finalizedEine Rechnung oder Gutschrift wird endgültig.
invoice.paidEine endgültige Rechnung wird als bezahlt markiert.
pingEine 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.

  1. Lesen Sie t und v1 aus dem Header.
  2. Berechnen Sie HMAC-SHA256 über t + "." + roher Body mit Ihrem Geheimnis.
  3. Vergleichen Sie das Ergebnis mit v1, mit einem Vergleich in konstanter Zeit.
  4. 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.