Webhooks konfigurieren

Richten Sie Webhooks ein, um Echtzeit-Benachrichtigungen für Nachrichten, Zustellstatus-Updates und Kampagnen-Events zu erhalten.

message.failed - Zustellung fehlgeschlagen

campaign.completed - Kampagne abgeschlossen

Ein Event tritt auf (z.B. Nachricht empfangen)

Wenn kein 200, versuchen wir es mit exponentiellem Backoff erneut

Events: Wählen Sie, welche Events Sie empfangen möchten

Ihre URL öffentlich zugänglich ist (nicht localhost)

Ihr SSL-Zertifikat gültig ist (nicht selbstsigniert)

Verwendung von geparsten JSON statt rohen Body

Falsches Webhook-Secret (erneut aus Einstellungen kopieren)

Speichern Sie die Event-ID und prüfen Sie auf Duplikate vor der Verarbeitung

Machen Sie Ihre Event-Handler idempotent

Antworten Sie so schnell wie möglich mit 200 (asynchron verarbeiten)

Eindeutige Event-ID (zur Deduplizierung verwenden)

Event-Typ-String (z. B. message.received)

ISO-8601-Zeitstempel, wann das Event aufgetreten ist

ID der Ressource, die das Event ausgelöst hat

Event-spezifischer Payload (variiert je nach Event-Typ)

Das attachments-Array ist nur vorhanden, wenn die Nachricht Medien enthält. Jeder Anhang enthält eine eindeutige id, content_type, file_size und zwei Download-URLs. Unterstützte Typen: image, video, audio, document, sticker.

url — Stabiler API-Endpoint. Erfordert Authentifizierung (API-Key oder Session-Token). Läuft nie ab.

signed_url — Vorsignierte GCS-URL. Keine Authentifizierung erforderlich. Läuft nach 24 Stunden ab.

Falls der Plattform-Medien-Download fehlschlaegt, werden die Roh-Plattformdaten mit einem "source": "platform"-Marker anstelle der angereicherten Felder durchgereicht. Nicht-Datei-Typen (Standort, Kontakte, Reaktionen) sind davon nicht betroffen.

Jedes Event, das ein Kontakt-Objekt enthaelt, liefert auch ein contact_methods[]-Array mit allen Identifikatoren des Kontakts (priorisierter zuerst). Die Felder phone und email auf der obersten Ebene bleiben aus Gruenden der Abwaertskompatibilitaet erhalten.

Schnellantwort- und Listenauswahlen kommen als message_type "button" an. Die Beschriftung steht in "text", ein strukturiertes "meta.button"-Objekt liefert id und payload – so kann die Auswahl direkt geroutet werden, ohne den Text zu parsen.

Beispiel mit Button-Klick anzeigen (Schnellantwort / Liste)

Stabiler Bezeichner des Buttons, wie beim Versand der Nachricht definiert.

Payload des Kanals (entspricht der id bei Schnellantworten).

Lesbare Beschriftung, die der Nutzer gesehen und getippt hat.

Ausgehende Nachrichten mit Dateianhangen enthalten das gleiche angereicherte Anhangs-Schema (id, url, signed_url, content_type, file_size) wie eingehende Nachrichten.

Das error-Feld befindet sich auf Datenebene (nicht innerhalb von message.meta). Das vollstaendige conversation- und contact-Objekt sind ebenfalls enthalten.

Status-Update-Events (delivered, read) verwenden ein vereinfachtes conversation-Objekt ohne bot_session_id oder last_*_at-Zeitstempelfelder. Das contact_method-Objekt ist nicht enthalten.

E-Mail-Unterhaltungsobjekte enthalten zusätzliche Felder: email_integration_id und email_thread_id für den Threading-Kontext.

Das reopened-Event enthält weniger Unterhaltungsfelder als andere Unterhaltungs-Events (kein bot_session_id, last_*_at-Zeitstempel oder subject).

contact.updated und contact.deleted verwenden die gleiche Struktur. Das type-Feld des Events unterscheidet zwischen ihnen.

Rohen Request-Body abrufen (vor dem JSON-Parsing)

HMAC-SHA256 mit Ihrem Webhook-Secret berechnen

Mit dem X-SendSeven-Signature-Header vergleichen

Timing-sichere Vergleichsfunktion verwenden, um Timing-Angriffe zu verhindern

Webhooks sind HTTP-Callbacks, mit denen SendSeven Echtzeit-Events an Ihre Anwendung sendet. Statt die REST API abzufragen, erhält Ihr Endpoint sofortige Benachrichtigungen, wenn etwas Wichtiges passiert – eine Nachricht trifft ein, eine Unterhaltung endet, ein Kontakt wird erstellt oder der Zustellstatus aendert sich. Jede Webhook-Anfrage ist HMAC-signiert für Sicherheit und wird bei Fehlern automatisch mit exponentiellem Backoff wiederholt, damit keine Events verloren gehen.

Ein SendSeven-Konto mit mindestens einem verbundenen Kanal

Ein öffentlicher HTTPS-Endpoint, der HTTP-POST-Anfragen empfangen kann

Ein gueltiges SSL-Zertifikat (Let's Encrypt funktioniert hervorragend)

Grundlegendes Verstaendnis von REST APIs und JSON

SendSeven-Dashboard Webhooks-Seite mit hervorgehobenem Button 'Endpoint hinzufügen'

Dialog 'Endpoint hinzufügen' mit HTTPS-URL-Feld und Event-Abonnements in SendSeven

Popup 'Webhook erfolgreich erstellt' mit angezeigtem Secret Key und Kopier-Button

Webhook-Detailseite mit Endpoint-URL, abonnierten Events, Zustellhistorie und Gesundheitsstatus in SendSeven

Automatisch beim Erstellen eines Webhooks über das Dashboard

Automatisch beim Erstellen eines Webhooks über die API (POST /api/v1/webhook-endpoints)

Automatisch wenn die Webhook-URL aktualisiert wird

Auf Anfrage über den Verify-Endpoint (POST /api/v1/webhook-endpoints/{id}/verify)

1. Webhook-Endpunkt erstellen
2. Webhook in SendSeven registrieren
3. Zu empfangende Event-Typen auswählen
4. Webhook-Verifizierung durchführen
5. Webhook-Signatur überprüfen
6. Eingehende Events verarbeiten
7. Mit Beispiel-Events testen