Einen Webhook einrichten

Endpunkt registrieren

Registriere eine Webhook-URL — unter Einstellungen/Webhooks im Portal oder mit POST /portal/webhooks. v1 verdrahtet das Ereignis message.inbound. Das Signatur-Secret wird genau einmal bei der Registrierung zurückgegeben — speichere es; du brauchst es, um Zustellungen zu verifizieren.

Die message.inbound-Payload

Empfängt Servus eine eingehende Nachricht, POSTet es einen JSON-Body an jede abonnierte URL:

• { "event": "message.inbound", "tenantId", "conversationId", "contactId", "messageId", "channel": "WhatsApp", "fromAddress": "+15551230000", "body": "Hi there", "receivedAtUtc": "…" }
• Hinweis: channel ist hier der Kanalname als String (z. B. "WhatsApp") — die einzige Stelle, an der die API einen Namen statt einer Zahl ausgibt.

Signatur verifizieren — immer

Jede Zustellung trägt einen X-Servus-Signature-Header: ein HMAC-SHA256 über die exakten Request-Body-Bytes, mit deinem Signatur-Secret verschlüsselt, als Kleinbuchstaben-Hex. Verifiziere ihn, bevor du der Payload vertraust, gegen den rohen Body (vor dem JSON-Parsen — erneutes Serialisieren kann Bytes ändern und die Signatur brechen), mit einem konstantzeitigen Vergleich.

• Mit dem SDK: verifyWebhookSignature(rawBody, req.header(SERVUS_SIGNATURE_HEADER), secret).
• Ohne: createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex'), dann timingSafeEqual gegen den Header.
• Eine falsche/fehlende Signatur sollte mit 401 abgelehnt und die Payload ignoriert werden.

Retries und Lebenszyklus

Webhooks wiederholen mit Backoff bei Fehlern — dein Endpunkt sollte idempotent sein (de-dupe über messageId). Du kannst ein Abo jederzeit deaktivieren/aktivieren oder löschen. Siehe das lauffähige verify-webhook.mjs-Beispiel im SDK.