Webhooks API v1.0 • Event Dispatcher

Echtzeit-Webhooks Dokumentation

Integrieren Sie externe TMS-, ERP- oder Benachrichtigungssysteme. Werden Sie sofort über Paketstatus, Registrierungen und Kundenpräferenzen informiert.

Im Admin-Dashboard konfigurieren Schema-Referenz

5 Schlüssel-Aktionen

Abonnieren Sie Statusänderungen, Paketerstellung, Fahrerregistrierung, Fahrerüberprüfung und Empfänger-Zustellpräferenzen.

GET & POST + Basic Auth

Unterstützt POST (JSON-Payload) oder GET (Query-Parameter), Basic Credentials, benutzerdefinierte Header und HMAC-SHA256 Signaturen.

Strikte Schemas & Logs

Jede Nachricht folgt einem wohldefinierten Schema. Vollständige Prüfprotokolle und Live-Testfunktion im Admin-Bereich.

1. Standard HTTP-Header Schema

Jeder ausgehende Webhook-Aufruf enthält verbindliche Standard-Header, um Herkunft, Event-Typ und Idempotenz sicherzustellen:

Header	Typ / Format	Beschreibung
X-Webhook-Event	string	Aktionsname (z.B. PACKAGE_STATUS_CHANGED, DRIVER_SIGNED_UP)
X-Webhook-Delivery-Id	string (del_...)	Eindeutige ID dieses Zustellversuchs zur Idempotenz-Prüfung
X-Webhook-Timestamp	ISO 8601	Zeitstempel der Auslösung (UTC)
X-Webhook-Signature	sha256=<hex>	HMAC-SHA256 Signatur (vorhanden, wenn im Admin ein Geheimnis konfiguriert wurde)
Authorization	Basic <base64>	Basic Auth Anmeldeinformationen (falls für den Endpunkt aktiviert)
Content-Type	application/json	Immer application/json bei POST Anfragen
User-Agent	string	`UniTracker-Webhook-Dispatcher/1.0`

2. Webhook Aktionen & Strikte Schemas

Wählen Sie eine Aktion aus, um das detaillierte Schema und Beispielaufrufe einzusehen.

Method:

Paketstatus geändertEvent: PACKAGE_STATUS_CHANGED

Wird ausgelöst, wenn sich der Zustellungsstatus eines Pakets ändert (z.B. In Zustellung, Zugestellt).

Feld-Definitionen (data-Objekt)

Field	Type	Required	Bedeutung
trackingId	string (TRK-XXXXXXXX)	YES	Eindeutige Sendungsnummer
previousStatus	string (PackageStatus)	OPTIONAL	Vorheriger Paketstatus
newStatus	string (PackageStatus)	YES	Neu zugewiesener Paketstatus
updatedAt	string (ISO 8601)	YES	Zeitstempel der Statusänderung
updatedBy	string	YES	Benutzer-ID des bearbeitenden Transporters
responsibleUserId	string	YES	ID des aktuell verantwortlichen Fahrers
responsibleUserName	string	OPTIONAL	Name des verantwortlichen Fahrers
note	string	OPTIONAL	Optionale Statusnotizen oder Übergabedetails
location	string	OPTIONAL	Geografischer Standort oder Hub
recipient	object	OPTIONAL	Öffentliche Empfängerdaten

POST JSON Body Beispiel

{
  "eventId": "del_x89a1bc",
  "event": "PACKAGE_STATUS_CHANGED",
  "timestamp": "2026-09-22T10:15:30.000Z",
  "apiVersion": "1.0",
  "data": {
    "trackingId": "TRK-98765432",
    "previousStatus": "PICKED_UP",
    "newStatus": "IN_TRANSIT",
    "updatedAt": "2026-09-22T08:30:00.000Z",
    "updatedBy": "usr-4412",
    "responsibleUserId": "usr-4412",
    "responsibleUserName": "Marco Transporter",
    "note": "Departed from central logistics distribution hub",
    "location": "Hub Frankfurt Nord",
    "recipient": {
      "name": "Anna Schmidt",
      "postalCode": "60311",
      "country": "Germany"
    }
  }
}

3. Authentifizierung & HMAC Signatur-Verifikation

HTTP Basic Authentication

Wenn Sie im Admin-Bereich Benutzernamen und Passwort hinterlegen, wird automatisch der RFC-konforme Basic Authorization Header gesendet:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Benutzerdefinierte Header (Custom Headers)

Sie können beliebig viele eigene Header konfigurieren, wie z.B. Bearer Tokens, API-Keys oder System-IDs:

X-API-Key: secret_token_xyz X-Tenant-Id: eu-central-01

HMAC-SHA256 Signatur prüfen

Wenn Sie ein gemeinsames Geheimnis (Secret) konfiguriert haben, sendet der Webhook-Dispatcher den Header "X-Webhook-Signature: sha256=<hash>". Prüfen Sie diese Signatur auf Ihrem Server, um Man-in-the-Middle Angriffe auszuschließen:

Node.js / TypeScript Example

import crypto from 'crypto';

export function verifyWebhook(rawBody: string, signatureHeader: string, secret: string): boolean {
  if (!signatureHeader || !signatureHeader.startsWith('sha256=')) return false;
  const signature = signatureHeader.slice(7);
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

4. Empfänger-Richtlinien & Best Practices

Schnelle 2xx-Antwort (Timeout: 8s)

Antworten Sie unverzüglich mit HTTP 200 oder 204. Führen Sie zeitintensive Datenbankberechnungen asynchron im Hintergrund aus.

Idempotenz über Delivery-ID

Speichern Sie bereits verarbeitete "X-Webhook-Delivery-Id"-Werte, um doppelte Verarbeitung bei Wiederholungsversuchen zu verhindern.

Benötigen Sie weitere Unterstützung? Rufen Sie die REST-Dokumentation oder den Administrator auf.

REST API Reference Admin Configuration