Zum Inhalt springen

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.

GVon

Webhooks v2 ist da

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

email.accepted

Zur Zustellung angenommen

email.scheduled

Für eine spätere Zustellung geplant

email.delivered

An den Mailserver des Empfängers zugestellt

email.bounced

Dauerhaft fehlgeschlagen (Hard Bounce)

email.attempted

Vorübergehender Zustellfehler

email.failed

Aufgrund eines spezifischen Fehlers fehlgeschlagen

email.rejected

Angenommen, dann abgelehnt

email.suppressed

Empfänger steht auf der Sperrliste

email.received

Eingehende E-Mail wurde angenommen

email.complained

Spam-Beschwerde registriert

email.clicked

Ein Link in der E-Mail wurde angeklickt

email.loaded

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-Digest
  • X-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

Content-Type

application/json

User-Agent

Emailit-Webhook/1.0

X-Emailit-Signature

HMAC-SHA256-Signatur

X-Emailit-Timestamp

Unix-Zeitstempel für die Signatur

Best Practices

  • Schnell antworten – Geben Sie sofort ein 2xx zurück und verarbeiten Sie den Payload asynchron in einem Hintergrundjob.
  • Duplikate behandeln – Dasselbe Event kann bei Wiederholungen mehrfach zugestellt werden. Verwenden Sie event_id zur 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-Timestamp und 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:

Loslegen

Starten Sie mit der Webhooks-Dokumentation oder springen Sie direkt zur API-Referenz, um Ihren ersten Webhook-Endpunkt anzulegen.

Teilen

Probieren Sie aus, worüber Sie gerade gelesen haben.

3.000 E-⁠Mails im Monat gratis. Keine Kreditkarte erforderlich.

3.000 E-⁠Mails im Monat kostenlos · Keine Kreditkarte erforderlich