Webhooks

Ein Webhook lässt SmartChat deiner Software sagen, dass etwas passiert ist, zum Beispiel ein neuer Kontakt oder eine zugestellte Nachricht. Du trägst einen Endpunkt ein (eine https-Adresse) und wählst die Ereignisse, die du willst. SmartChat sendet jedes Ereignis als POST mit einem JSON-Body an den Endpunkt.

Wie du einen Webhook einrichtest, steht unter Einen Webhook einrichten. Die Liste der Ereignisse steht auf der Ereignisseite.

#Was du empfängst

Header:

Header	Bedeutung
`SmartChat-Signature`	`t=<unix seconds>,v1=<hex>`. Beweist, dass die Zustellung von SmartChat kommt. So prüfst du sie.
`SmartChat-Event-Id`	ID des Ereignisses (`evt_...`). Für jeden Endpunkt gleich.
`SmartChat-Event-Type`	Der Ereignisname, zum Beispiel `contact.created`.
`SmartChat-Delivery-Id`	ID dieser Zustellung (`whd_...`).
`SmartChat-Delivery-Attempt`	Nummer dieses Versuchs, beginnend bei 1.
`User-Agent`	`SmartChat-Webhooks/2`
`Content-Type`	`application/json`

Body:

{
  "id": "evt_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "object": "event",
  "type": "contact.opted_out",
  "api_version": "2026-10-25",
  "created_at": "2026-10-25T09:41:07.412Z",
  "sequence": 128734,
  "account_id": "acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "livemode": true,
  "request_id": "req_01JAB9C3X7K2M4N5P6Q7R8S9T0",
  "data": {
    "object": { "object": "contact", "id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234", "optin_whatsapp": "opted_out" },
    "previous_attributes": { "optin_whatsapp": "confirmed" }
  }
}

Feld	Bedeutung
`id`	Ereignis-ID. Nutze sie, um doppelte Ereignisse zu finden.
`type`	Ereignisname.
`created_at`	Wann das Ereignis passiert ist, mit Millisekunden, in UTC.
`sequence`	Ein Zähler zum Sortieren von Ereignissen.
`request_id`	Die ID des API-Aufrufs, der das Ereignis ausgelöst hat, wenn es einen gab.
`data.object`	Das Objekt, um das es im Ereignis geht.
`data.previous_attributes`	Bei Änderungen: die alten Werte der geänderten Felder.

Der Body ist höchstens 256 KB groß. Wäre er größer, wird data.object auf object und id gekürzt und der Body bekommt "truncated": true. Lies das ganze Objekt mit der API.

#Was du tun musst

Prüfe die Signatur mit dem rohen Body. Code in Shell, Python und TypeScript.
Antworte schnell mit einem beliebigen 2xx-Status. SmartChat wartet 10 Sekunden. Erledige die eigentliche Arbeit, nachdem du geantwortet hast.
Rechne damit, dass Ereignisse doppelt ankommen. Die Zustellung erfolgt mindestens einmal. Behalte die id der Ereignisse, die du bearbeitet hast, und überspringe Wiederholungen.
Verlass dich nicht auf die Reihenfolge. Ereignisse können in anderer Reihenfolge ankommen. Sortiere mit sequence oder created_at.
Nutze https. Erlaubt ist nur https auf Port 443, ohne Benutzername oder Passwort in der Adresse und ohne Weiterleitungen. Interne und private Adressen werden abgelehnt (webhook_url_invalid). SmartChat prüft die Adresse beim Speichern und bei jeder Verbindung noch einmal.

Ein Konto kann bis zu 20 Endpunkte haben. Dieselbe Adresse zweimal im selben Konto ist ein Konflikt. Endpunkte gehören zum Konto, nicht zu einem Schlüssel: Den Schlüssel zu widerrufen, der einen Endpunkt angelegt hat, stoppt ihn nicht.

#Fehlschläge

Antwortet dein Endpunkt nicht mit 2xx, versucht SmartChat es später noch einmal. Den Zeitplan, die Zustände eines Endpunkts und was am Ende passiert, findest du unter Wiederholungen und Zustand.