Webhooks

Die Zustell-Webhooks von WeZend arbeiten pro Nachricht: Sie übergeben webhook_url direkt in der Sendeanfrage (oder pro Nachricht innerhalb einer Bulk-Anfrage), und Statusupdates für diese Nachricht werden dorthin gePOSTet, sobald sie eintreten. Für kontoweite Plattform-Events gibt es zusätzlich /v1/webhook-endpoints — siehe unten.

{
  "to": "+4512345678",
  "channel": "sms",
  "message": "Ihre Bestellung wurde versandt.",
  "webhook_url": "https://ihre-app.de/hooks/wezend"
}

Payload und Header

Jede Zustellung enthält:

• X-WeZend-Event — der Name des Events
• X-WeZend-Timestamp — Unix-ms-Zeitstempel, der in der Signatur verwendet wird
• X-WeZend-Signature — HMAC-SHA256 von ${timestamp}.${JSON.stringify(payload)}, mit dem Webhook-Signaturgeheimnis aus Einstellungen → Webhook-Secret

Jede Zustellung enthält zusätzlich die Legacy-Aliasse X-ZafeConnect-* derselben drei Header, beibehalten aus der Zeit vor dem Rebranding, damit bestehende Integrationen weiter verifizieren. Die Werte sind identisch mit den X-WeZend-*-Headern — verifizieren Sie gegen das Präfix, das Sie bereits verwenden.

Signatur verifizieren

const crypto = require("crypto");

function verify(rawBody, timestamp, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Wiederholungsversuche

Antwortet Ihr Endpoint nicht mit 2xx, wird die Zustellung 3-mal wiederholt — nach 30 Sekunden, 5 Minuten und schließlich 30 Minuten — und die Wiederholungen überstehen einen Neustart oder ein Deployment (sie sind dauerhaft in der Datenbank gespeichert, nicht in einer In-Memory-Queue). Antworten Sie schnell und verarbeiten Sie asynchron, statt langsame Arbeit im Request-Handler zu erledigen.

Plattform-Event-Webhooks

Neben den Zustell-Webhooks pro Nachricht können Sie kontoweite ausgehende Endpoints registrieren: POST /v1/webhook-endpoints mit { url, events } legt einen an (verwalten mit GET/PATCH/DELETE, und POST /v1/webhook-endpoints/:id/test stellt einen Ping zu). Beide Credential-Typen funktionieren — ein API-Key oder ein Dashboard-JWT aus POST /v1/auth/login — sodass sich eine serverseitige Integration selbst registrieren kann, ohne dass jemand das Dashboard öffnet. Jeder Endpoint erhält ein eigenes whsec_...-Signing-Secret, das nur bei der Erstellung angezeigt wird.

curl -X POST https://api.wezend.com/v1/webhook-endpoints \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/wezend", "events": ["contact.unsubscribed"] }'

Wurde der Key mit einer expliziten Scope-Liste ausgestellt, benötigt er write, um einen Endpoint anzulegen, zu ändern oder zu löschen. Ein Key mit nur read kann Endpoints auflisten, erhält bei den Mutationen aber 403 insufficient_scope, wobei der fehlende Scope im Response-Body genannt wird. Keys ohne Scope-Liste behalten den vollen Zugriff.

In events können neun Event-Typen abonniert werden. Ein Endpoint, der mit einem leeren events-Array registriert wird, erhält alle.

Abonnieren Sie contact.unsubscribed, um Ihre eigenen Einwilligungsdaten synchron zu halten. Bevor es dieses Event gab, hat nichts einen Opt-out aus WeZend heraus gemeldet: liegt Ihr System of Record woanders — ein CRM, ein Händlerportal, Ihre eigene Datenbank — gab es keine Möglichkeit zu erfahren, dass ein Kontakt mit STOP geantwortet hat, und Sie hätten ihn weiterhin als angemeldet behandelt. contact.bounced ist ein Zustellbarkeitssignal und kein ausdrücklicher Opt-out, halten Sie beides in Ihren eigenen Daten also getrennt.

Eingehende Zustellbestätigungen der Anbieter

Über die Endpoints /v1/webhooks/messente, /v1/webhooks/twilio, /v1/webhooks/vonage und /v1/webhooks/whatsapp melden vorgelagerte Netzbetreiber die Zustellung an die Plattform zurück — sie sind plattformintern und werden nicht von Ihnen konfiguriert; sie existieren, damit WeZend selbst die Status befüllen kann, die Sie über webhook_url und die Nachrichtenverlaufs-API sehen.