Webhook-Benachrichtigungen für Versand-Updates einrichten

Polling-basiertes Monitoring hat einen Nachteil: Es gibt immer eine Verzögerung zwischen dem Eintreten eines Events und Ihrer Benachrichtigung. Webhooks lösen dieses Problem, indem sie Events in Echtzeit an Ihren Endpoint pushen.

Dieser Artikel zeigt, wie Sie Webhook-Benachrichtigungen für Sendungs-Updates einrichten – von der Grundkonfiguration bis zur Signaturverifizierung und Retry-Logik.

Was sind Webhooks?

Webhooks sind HTTP-Callbacks: Wenn ein Ereignis eintritt, sendet der Server eine HTTP-POST-Anfrage an eine von Ihnen definierte URL. Im Kontext von Sendungs-Monitoring bedeutet das: Sobald sich der Status einer Sendung ändert, wird Ihr System sofort informiert.

{
  "event": "shipment.exception",
  "timestamp": "2026-01-15T14:32:00Z",
  "data": {
    "trackingNumber": "00340434161094042684",
    "carrier": "DHL",
    "customerRef": "ORDER-4521",
    "status": "DELIVERY_FAILED",
    "previousStatus": "IN_TRANSIT",
    "priority": "HIGH",
    "description": "Delivery attempt failed - recipient not available",
    "location": "Berlin, DE"
  }
}

Webhook einrichten

Die Einrichtung umfasst drei Schritte: Endpoint erstellen, URL konfigurieren, Signatur verifizieren.

1. Einen Endpoint erstellen

Ihr Webhook-Endpoint muss HTTP-POST-Anfragen mit JSON-Payload akzeptieren und mit einem 200-Status antworten. Bei jedem anderen Statuscode wird der Zustellversuch als fehlgeschlagen gewertet und automatisch wiederholt.

// Express example: acknowledge immediately, process async
import express from 'express';
import { addToQueue } from './queue';

const app = express();
app.use(express.json());

app.post('/webhooks/shipping', async (req, res) => {
  // 1. Verify signature (see below)
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Enqueue for async processing
  await addToQueue('shipping-events', req.body);

  // 3. Acknowledge immediately
  res.status(200).json({ received: true });
});

2. URL konfigurieren

Registrieren Sie Ihre Webhook-URL über die ShipTriage API oder das Dashboard. Sie können auch ein Secret festlegen, das zur Signierung der Payloads verwendet wird.

3. Signatur verifizieren

Jeder Webhook-Payload enthält einen X-ShipTriage-Signature-Header mit einer HMAC-SHA256-Signatur. Verifizieren Sie diese Signatur, um sicherzustellen, dass der Payload tatsächlich von ShipTriage stammt.

import crypto from 'crypto';

function verifySignature(req: express.Request): boolean {
  const signature = req.headers['x-shiptriage-signature'] as string;
  if (!signature) return false;

  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
    .update(payload)
    .digest('hex');

  // Use timingSafeEqual to prevent timing attacks
  // Check length first -- timingSafeEqual throws if lengths differ
  if (signature.length !== expected.length) return false;

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Retry-Logik

Wenn Ihr Endpoint nicht erreichbar ist oder einen Fehler zurückgibt, versucht ShipTriage die Zustellung automatisch erneut mit exponentiellem Backoff: nach 1, 5 und 30 Minuten.

Integrationsbeispiele

Slack-Integration

Leiten Sie Webhook-Events an einen Slack-Channel weiter, um Ihr Team sofort über Sendungsprobleme zu informieren.

Microsoft Teams

Nutzen Sie eingehende Webhooks in Teams, um Sendungsbenachrichtigungen in Ihrem Operations-Channel zu empfangen.

Eigenes System

Verarbeiten Sie Webhook-Events in Ihrem eigenen Backend, um Sendungsdaten in Ihrem OMS, CRM oder Kundensupport-System zu aktualisieren.