Ankündigung von Webhooks v2

Wir starten Webhooks v2 – eine komplette Überarbeitung der Art, wie Emailit Echtzeit-Event-Benachrichtigungen an Ihre Anwendungen übermittelt. Mit 36 Event-Typen in 9 Ressourcen-Kategorien, kryptographischer Signatur-Verifizierung und einer robusten Wiederholungsrichtlinie bietet Ihnen Webhooks v2 alles, was Sie für zuverlässige, event-gesteuerte Integrationen benötigen.

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 verfolgen den kompletten Zustellungslebenszyklus:

CRUD-Events für Domains, Zielgruppen, Abonnenten, Kontakte, Vorlagen, Unterdrückungen, E-Mail-Verifizierungen und E-Mail-Verifizierungslisten – jeweils mit .created-, .updated- und .deleted-Events.

Einheitliche Event-Struktur

Jede Webhook-Payload folgt derselben Struktur, was es einfach macht, einen einzigen Handler für alle Events zu erstellen:

{
  "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.

HMAC-SHA256-Signatur-Verifizierung

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) zu verwenden, 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 exponentieller Verzögerung

Wenn Ihr Endpoint nicht innerhalb von 30 Sekunden mit einem 2xx antwortet, wiederholt Emailit automatisch:

Das sind insgesamt 7 Versuche über etwa 41 Stunden. Nach dem letzten Versuch wird der Webhook automatisch deaktiviert. Sie können ihn jederzeit über das Dashboard wieder aktivieren.

Anfrage-Format

Alle Webhook-Anfragen sind POST mit einem JSON-Body. Jede Anfrage enthält diese Header:

Best Practices

• Schnell antworten — Geben Sie sofort ein 2xx zurück und verarbeiten Sie die Payload asynchron in einem Hintergrund-Job.
• Duplikate behandeln — Dasselbe Event kann bei Wiederholungen mehrfach zugestellt werden. Verwenden Sie event_id zur Deduplizierung.
• Signaturen verifizieren — Validieren Sie immer den X-Emailit-Signature-Header, um zu bestätigen, 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:

• Einführung — Überblick und Funktionsweise von Webhooks
• Event-Typen — Vollständige Liste aller 36 Event-Typen
• Webhook-Anfragen — Anfrage-Format, Header und Wiederholungsrichtlinie
• Anfrage-Signatur — Signatur-Verifizierung mit Code-Beispielen in 5 Sprachen

Loslegen

Besuchen Sie die Webhooks-Dokumentation, um zu beginnen, oder springen Sie direkt zur API-Referenz, um Ihren ersten Webhook-Endpoint zu erstellen.