Webhook-Anfragen

Wenn ein Ereignis auftritt, sendet Emailit eine HTTP-POST-Anfrage an Ihre konfigurierte Webhook-URL. Diese Seite beschreibt das Anfrageformat, die Header und das Übertragungsverhalten.

Anfrageformat

Alle Webhook-Anfragen werden als POST-Anfragen mit einem JSON-Body gesendet:

Methode: POST
Content-Type: application/json
Timeout: 30 Sekunden

Jede Webhook-Anfrage enthält die folgenden Header:

Header	Beschreibung
`Content-Type`	`application/json`
`User-Agent`	`Emailit-Webhooks/2.0`
`X-Emailit-Signature`	HMAC-SHA256-Signatur zur Authentizitätsprüfung
`X-Emailit-Timestamp`	Unix-Zeitstempel der Anfragensignierung

Anfrage-Body

Der Anfrage-Body enthält die Ereignisdaten als JSON:

{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}

Erwartete Antwort

Ihr Endpunkt sollte einen 2xx-Statuscode (z.B. 200, 201, 204) zurückgeben, um den Empfang zu bestätigen. Jeder andere Statuscode wird als Fehler behandelt.

Wiederholungsrichtlinie

Falls Ihr Endpunkt nicht innerhalb von 30 Sekunden mit einem 2xx-Statuscode antwortet, wiederholt Emailit die Zustellung nach folgendem Schema:

Versuch	Verzögerung
0	5 Sekunden
1	5 Minuten
2	30 Minuten
3	2 Stunden
4	5 Stunden
5	10 Stunden
6	24 Stunden

Nach Versuch 6 (insgesamt 7 Versuche) wird der Webhook automatisch deaktiviert. Sie können ihn über das Emailit-Dashboard wieder aktivieren.

Reihenfolge

Webhook-Ereignisse werden nahezu in Echtzeit übertragen, jedoch ist die Reihenfolge nicht garantiert. Verwenden Sie die event_id und Zeitstempel in den Ereignisdaten, um die Reihenfolge in Ihrer Anwendung zu handhaben.

IP-Adressen

Webhook-Anfragen werden von Emailits Infrastruktur gesendet. Falls Sie IPs auf eine Whitelist setzen müssen, wenden Sie sich an den Support für die aktuelle Liste der ausgehenden IP-Adressen.

Best Practices

Schnell antworten — Verarbeiten Sie den Webhook asynchron und geben Sie sofort einen 2xx-Code zurück. Führen Sie aufwändige Verarbeitungen in einem Hintergrund-Job aus.
Duplikate handhaben — Verwenden Sie die event_id zur Deduplizierung von Ereignissen. Dasselbe Ereignis kann bei Wiederholungsversuchen mehrfach zugestellt werden.
Signaturen prüfen — Validieren Sie immer den X-Emailit-Signature-Header, um sicherzustellen, dass die Anfrage von Emailit stammt. Siehe Anfrage-Signatur.