Zum Inhalt springen
Alpha auf Einladung. Funktionen und Grenzen können sich durch unsere Testerfahrungen ändern.

Webhooks

Ein Webhook schickt ein HTTPS-POST an Ihren Server, wenn sich bei einer Ihrer Nachrichten etwas ändert. So muss Ihre Anwendung die API nicht abfragen.

Endpunkte richtet weneed auf Anfrage ein. Schreiben Sie mit Ihrer HTTPS-URL und den benötigten Ereignissen an help@weneed.email. Nach der Aktivierung stellt der Dienst Benachrichtigungen automatisch zu.

Ereignis Gesendet, wenn
email.accepted weneed.email die Nachricht gespeichert hat.
email.submitted die Nachricht an den empfangenden Server übergeben wurde.
email.delivered der empfangende Server sie angenommen hat.
email.bounced der empfangende Server sie abgelehnt hat, sofort oder später.
email.complained die Empfängerin oder der Empfänger sie als Spam markiert hat.
email.rejected sie nicht gesendet werden konnte und nicht erneut versucht wird.
email.suppressed sie nicht gesendet wurde, weil die Adresse gesperrt ist.
email.expired ihr expires_at vor dem Versand überschritten war.
email.cancelled sie vor dem Versand abgebrochen wurde.
email.submission_unknown sich nicht feststellen lässt, ob der empfangende Server sie übernommen hat.
email.delivery_delayed der empfangende Server eine vorübergehende Verzögerung gemeldet hat und es weiter versucht. Das ist keine Zustellung.
domain.status_changed eine Ihrer Absenderdomains eine Prüfung nicht mehr besteht oder wieder besteht.

Ereignisse enthalten nur Metadaten. Betreff, Inhalt, Empfängeradresse und Header sind nie enthalten. Neue Felder und Ereignistypen können hinzukommen; ignorieren Sie unbekannte.

Jedes Ereignis hat denselben Umschlag. Der Inhalt sind genau die Bytes, die beim Erfassen des Ereignisses gespeichert wurden: Eine Wiederholung oder ein Replay sendet sie unverändert, die Signatur bleibt gültig.

{
"id": "0f8c…",
"type": "email.bounced",
"api_version": "v1",
"occurred_at": "2026-10-15T10:00:00.123Z",
"received_at": "2026-10-15T10:00:01.456Z",
"project_id": "5b1e…",
"simulated": false,
"data": {
"email_id": "7d2a…",
"submission_state": "submitted",
"recipient_outcome": "bounced",
"reason": null,
"tags": { "order": "1234" },
"attempt_number": 1,
"feedback": { "action": "failed", "status": "5.1.1" }
}
}

Bei email.*-Ereignissen enthält data die Fakten der Nachricht zum Zeitpunkt, als das Ereignis erfasst wurde:

Feld Bedeutung
email_id Die Nachrichten-ID aus POST /v1/emails.
submission_state Der Einlieferungszustand zu diesem Zeitpunkt.
recipient_outcome pending, delivered_to_server, delivery_unknown, bounced, suppressed oder rejected, oder null, wenn keines erfasst wurde.
reason Warum die Nachricht in diesem Zustand ist: code, category (wait, fix, contact_support, none) und retry (safe_same_key, do_not_resend, not_applicable). null, wenn der Zustand keine Ursache hat. Siehe Ursachencodes.
tags Die Tags, die Sie mit der Nachricht gesendet haben, oder null, wenn historische Tags nicht gespeichert wurden.
attempt_number Der Versandversuch, den das Ereignis betrifft, oder null vor dem ersten Versuch.
feedback Nur bei email.bounced: action und erweiterter status-Code der Zustellmeldung, oder null, wenn keine Meldung einging.

Jedes Ereignis beschreibt seinen eigenen Zeitpunkt. Ein späteres Ereignis kann neuere Fakten enthalten, und Ereignisse können in anderer Reihenfolge ankommen: Verwenden Sie occurred_at oder lesen Sie den aktuellen Zustand mit GET /v1/emails/{id}.

Bei domain.status_changed enthält data die domain_id, status (degraded oder recovered) und die Ursache cause: domain_revoked, ownership_stale, authentication_stale, authentication_failed oder preparation_pending. DNS-Werte sind nicht enthalten; die Details sehen Sie im Projekt in Control.

Ereignisse, die vor diesen Feldern erfasst wurden, enthalten nur data.email_id, auch bei einem Replay.

Öffnen Sie die Webhook settings Ihres Projekts. Lassen Sie sich beim Endpunkt das Signaturgeheimnis anzeigen. Das verlangt Ihren Authenticator-Code und funktioniert einmal: Bestätigen Sie, dass Sie bereit sind, es zu speichern, lassen Sie es anzeigen und legen Sie es sofort im Secret-Store Ihres Empfängers ab.

Lud die Seite nicht und ist das Geheimnis verloren, schreiben Sie an help@weneed.email, damit der Endpunkt deaktiviert und neu angelegt wird.

Jede Anfrage hat drei Header: Webhook-Id, Webhook-Timestamp (Unix-Sekunden) und Webhook-Signature (v1, gefolgt von der Signatur).

  1. Dekodieren Sie das Geheimnis aus Base64 in 32 Bytes.
  2. Nehmen Sie den unveränderten Request-Body, vor jedem JSON-Parsing.
  3. Berechnen Sie HMAC-SHA256 über Webhook-Id + "." + Webhook-Timestamp + "." + Body und kodieren Sie das Ergebnis in Base64.
  4. Vergleichen Sie es mit der Signatur nach v1,, mit einem Vergleich in konstanter Zeit. Während ein Geheimnis ersetzt wird, kann der Header zwei Signaturen enthalten, getrennt durch ein Leerzeichen; akzeptieren Sie jede davon.
  5. Lehnen Sie Zeitstempel ab, die mehr als fünf Minuten von Ihrer Uhr abweichen.
  6. Überspringen Sie Ereignisse, deren Webhook-Id Sie schon verarbeitet haben.
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, headers, secretBase64) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = createHmac('sha256', Buffer.from(secretBase64, 'base64'))
.update(`${id}.${timestamp}.`)
.update(rawBody)
.digest();
return headers['webhook-signature']
.split(' ')
.filter((part) => part.startsWith('v1,'))
.map((part) => Buffer.from(part.slice(3), 'base64'))
.some((sig) => sig.length === expected.length && timingSafeEqual(sig, expected));
}
  • Bestätigen Sie mit einer beliebigen 2xx-Antwort, innerhalb von 10 Sekunden.
  • Jede andere Antwort oder ein Timeout wird nach etwa 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 8 Stunden, 24 Stunden und 48 Stunden wiederholt, höchstens 72 Stunden lang.
  • Eine Wiederholung hat dieselbe Webhook-Id und denselben Body, mit neuem Zeitstempel und neuer Signatur.
  • Antworten Sie 410 Gone, um den Endpunkt zu deaktivieren.

Dasselbe Ereignis kann mehrmals und in anderer Reihenfolge ankommen. Ein Webhook ist nie ein Grund, eine E-Mail erneut zu senden.

View webhook history listet jede Zustellung mit ihrem letzten Versuch und Ergebnis. Fehlgeschlagene Zustellungen erscheinen auch in Ihrer Projektübersicht.

Um Zustellungen zu stoppen, wählen Sie Review disabling this endpoint und bestätigen Sie. Ausstehende Benachrichtigungen werden zurückgehalten. Eine bereits laufende kann noch ankommen.