Ankündigungen5 Min. Lesezeit
Webhooks v2 ist da
Webhooks v2 ist da: 36 Event-Typen, HMAC-SHA256-Signaturen, automatische Wiederholungen und eine vollständige Dokumentation für jeden Payload.
GVonGeorge

Wir starten Webhooks v2, eine komplette Überarbeitung der Art, wie Emailit Event-Benachrichtigungen in Echtzeit an Ihre Anwendungen übermittelt. Mit 36 Event-Typen in 9 Ressourcenkategorien, kryptografischer Signaturprüfung und einer robusten Wiederholungsstrategie bietet Ihnen Webhooks v2 alles, was Sie für zuverlässige, eventgesteuerte Integrationen brauchen.
Was ist neu
36 Event-Typen in 9 Ressourcen
Webhooks v2 deckt jede Ressource in Emailit ab. Sie können genau die Events abonnieren, die Sie interessieren, oder all_events verwenden, um alles zu erhalten.
E-Mail-Events bilden den kompletten Lebenszyklus der Zustellung ab:
Event | Beschreibung |
|---|---|
| Zur Zustellung angenommen |
| Für eine spätere Zustellung geplant |
| An den Mailserver des Empfängers zugestellt |
| Dauerhaft fehlgeschlagen (Hard Bounce) |
| Vorübergehender Zustellfehler |
| Aufgrund eines spezifischen Fehlers fehlgeschlagen |
| Angenommen, dann abgelehnt |
| Empfänger steht auf der Sperrliste |
| Eingehende E-Mail wurde angenommen |
| Spam-Beschwerde registriert |
| Ein Link in der E-Mail wurde angeklickt |
| E-Mail-Inhalt wurde geladen (geöffnet) |
CRUD-Events für Domains, Kontaktlisten, Abonnenten, Kontakte, Vorlagen, Sperrungen, E-Mail-Verifizierungen und Verifizierungslisten, jeweils mit den Events .created, .updated und .deleted.
Einheitliche Event-Struktur
Jeder Webhook-Payload folgt derselben Struktur, sodass Sie ganz einfach einen einzigen Handler für alle Events bauen können:
{
"event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
"type": "email.delivered",
"data": {
"object": {
"id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
"object": "email",
...
}
}
}Die event_id identifiziert jedes Event eindeutig, type teilt Ihnen mit, was passiert ist, und data.object enthält die vollständige Ressource zum Zeitpunkt des Events.
Signaturprüfung mit HMAC-SHA256
Jede Webhook-Anfrage wird mit Ihrem Webhook-Secret mittels HMAC-SHA256 signiert. Die Signatur wird über {timestamp}.{rawBody} berechnet, sodass Sie Authentizität und Aktualität in einem Schritt verifizieren können.
Jede Anfrage enthält zwei Header:
X-Emailit-Signature– der HMAC-SHA256-Hex-DigestX-Emailit-Timestamp– der Unix-Zeitstempel, der in der Signatur verwendet wurde
Wir empfehlen dringend einen zeitkonstanten Vergleich (z. B. crypto.timingSafeEqual in Node.js), um Timing-Angriffe zu verhindern, und Anfragen mit Zeitstempeln, die älter als ein paar Minuten sind, abzulehnen, um sich vor Replay-Angriffen zu schützen.
Vollständige Verifizierungsbeispiele in Node.js, Python, PHP, Ruby und Go finden Sie in der Dokumentation zur Anfrage-Signatur.
Automatische Wiederholungen mit exponentiellem Backoff
Wenn Ihr Endpunkt nicht innerhalb von 30 Sekunden mit einem 2xx antwortet, wiederholt Emailit die Anfrage automatisch:
Versuch | Verzögerung |
|---|---|
0 | 5 Sekunden |
1 | 5 Minuten |
2 | 30 Minuten |
3 | 2 Stunden |
4 | 5 Stunden |
5 | 10 Stunden |
6 | 24 Stunden |
Das sind insgesamt 7 Versuche über etwa 41 Stunden. Nach dem letzten Versuch wird der Webhook automatisch deaktiviert. Sie können ihn jederzeit in der Weboberfläche wieder aktivieren.
Format der Anfragen
Alle Webhook-Anfragen sind POST mit einem JSON-Body. Jede Anfrage enthält diese Header:
Header | Beschreibung |
|---|---|
|
|
|
|
| HMAC-SHA256-Signatur |
| Unix-Zeitstempel für die Signatur |
Best Practices
- Schnell antworten – Geben Sie sofort ein
2xxzurück und verarbeiten Sie den Payload asynchron in einem Hintergrundjob. - Duplikate behandeln – Dasselbe Event kann bei Wiederholungen mehrfach zugestellt werden. Verwenden Sie
event_idzur Deduplizierung. - Signaturen verifizieren – Prüfen Sie immer den Header
X-Emailit-Signature, um sicherzustellen, dass die Anfrage von Emailit stammt. - Vor Replay-Angriffen schützen – Prüfen Sie den
X-Emailit-Timestampund lehnen Sie Anfragen ab, die älter als ein paar Minuten sind.
Vollständige Dokumentation
Wir haben eine umfassende Dokumentation für Webhooks v2 mit detaillierten Payload-Beispielen und Feldbeschreibungen für alle 36 Events veröffentlicht:
- Einführung – Überblick und Funktionsweise von Webhooks
- Event-Typen – Vollständige Liste aller 36 Event-Typen
- Webhook-Anfragen – Format der Anfragen, Header und Wiederholungsstrategie
- Anfrage-Signatur – Signaturprüfung mit Codebeispielen in 5 Sprachen
Loslegen
Starten Sie mit der Webhooks-Dokumentation oder springen Sie direkt zur API-Referenz, um Ihren ersten Webhook-Endpunkt anzulegen.


