Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

Webhooks

Signierte Ereigniszustellungen an Ihren Endpunkt, mit Wiederholungen und einem Zustellprotokoll.

Ein Webhook sendet jedes Mal, wenn etwas geschieht, ein HTTP-POST an Ihren Endpunkt: eine E-Mail wird zugestellt, ein Kontakt meldet sich ab, eine E-Mail trifft ein. Fügen Sie Endpunkte im Dashboard unter Webhooks oder mit POST /webhooks hinzu und wählen Sie, welche Ereignisse jeder erhält. Die SDKs verifizieren Zustellungen mit verifyWebhook (Node.js) und verify_webhook (Python).

curl -X POST "https://api.billionsend.com/webhooks" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://example.com/webhooks/email",
    "events": ["email.delivered", "email.bounced"]
  }'

Die Antwort enthält das signing_secret (whsec_...). GET /webhooks/{id} gibt es erneut zurück, und Listenzeilen enthalten es nie.

Ereignisse

E-Mail-Ereignisse

Ereignis Wird ausgelöst, wenn
email.scheduled Eine E-Mail mit einem scheduled_at in der Zukunft angenommen wurde.
email.sent Die E-Mail an den Mail-Dienst übergeben wurde.
email.delivered Der Server des Empfängers sie angenommen hat.
email.delivery_delayed Die Zustellung wiederholt wird (volles Postfach, Greylisting).
email.bounced Die E-Mail gebounct ist. data.bounce.type ist Permanent (ein Hard Bounce: Die Adresse wird außerdem gesperrt), Transient oder Undetermined (nicht gesperrt).
email.complained Der Empfänger sie als Spam markiert hat. Die Adresse wird ebenfalls gesperrt.
email.failed Die E-Mail nie gesendet wird. data.failed.reason nennt den Grund.
email.suppressed Die E-Mail vor dem Versand gestoppt wurde. data.suppressed.reason nennt den Grund.
email.opened Eine Person sie geöffnet hat (erfordert Öffnungs-Tracking bei der Domain).
email.clicked Eine Person einen getrackten Link angeklickt hat (erfordert Klick-Tracking).
email.prefetched Eine Maschine, keine Person, das Tracking-Pixel geladen oder einem Link gefolgt ist (Datenschutz-Proxys, Sicherheitsscanner). Nur auf Anforderung, siehe unten.
email.received Eine Nachricht bei einer Ihrer Empfangsdomains eingegangen ist. data.email_id lesen Sie mit GET /emails/receiving/{id}.

email.prefetched ist nur auf Anforderung verfügbar, wie jedes inbox.*-Ereignis: Ein Endpunkt erhält es nur, wenn er das Ereignis nennt, nie über „alle Ereignisse“.

Konto-Ereignisse

Diese gehören zu keiner E-Mail. data beschreibt den Status Ihres Teams.

Ereignis Wird ausgelöst, wenn
deliverability.warning Ihre Hard-Bounce- oder Beschwerderate die Warngrenze überschritten hat.
deliverability.paused Die Rate die Pausengrenze überschritten hat und neue Sendungen abgelehnt werden, bis sie sich erholt.
quota.warning 80 % Ihres Kontingents verbraucht sind (bei Free das heutige Limit, bei kostenpflichtigen Tarifen das enthaltene Volumen des Abrechnungszeitraums).
quota.reached Das Kontingent aufgebraucht ist.
quota.paused Nur Free: Sendungen werden bis Mitternacht UTC zurückgehalten oder bis Sie upgraden.

Zielgruppen-Ereignisse

Sie werden ausgelöst, sobald sich ein Kontakt oder die Sperrliste ändert, egal wer sie geändert hat. data enthält den Kontakt (id, email, first_name, last_name, unsubscribed, created_at, updated_at) und eine source: api, dashboard, hosted_page oder one_click.

Ereignis Wird ausgelöst, wenn Zusätzliche data
contact.created Ein Kontakt hinzugefügt wurde.
contact.updated Name, Eigenschaften oder das Flag „abgemeldet“ sich geändert haben.
contact.deleted Ein Kontakt gelöscht wurde. Nach einer Löschung steht bei email der Wert [erased], richten Sie sich also nach id.
contact.unsubscribed Ein Empfänger einen Abmeldelink genutzt hat oder Sie unsubscribed auf true gesetzt haben. domain_id, domain_name (beide null bei einer teamweiten Abmeldung)
contact.resubscribed Eine Abmeldung zurückgenommen wurde. domain_id, domain_name
contact.topic_opt_in, contact.topic_opt_out Das Abonnement eines Kontakts für ein Thema sich geändert hat. topic_id, topic_name
suppression.added, suppression.removed Eine Adresse auf die Sperrliste kam oder sie verlassen hat. id, email, origin, source, source_id, created_at

Was domain_id bedeutet, steht unter Abmeldungen.

Postfach-Ereignisse

Postfächer senden inbox.created, inbox.updated, inbox.deleted, inbox.expired, inbox.thread.created, inbox.thread.folder.updated, inbox.thread.labels.updated, inbox.email.received, inbox.email.sent, inbox.email.quarantined, inbox.draft.created, inbox.draft.updated, inbox.draft.sent, inbox.draft.deleted und inbox.draft.send_failed (ein geplanter Versand wurde abgelehnt; ein eigenes Ereignis von BillionSend, mit dem Entwurf und error: { name, message }). Alle sind nur auf Anforderung verfügbar.

data enthält immer source (api, dashboard oder system) und inbox_id. E-Mail- und Entwurfsobjekte tragen nie den Text: Rufen Sie ihn über die API ab.

Um einen Endpunkt auf einige Postfächer zu beschränken, senden Sie inbox_ids (bis zu 100 Postfächer Ihres Teams; null bedeutet jedes Postfach, eine leere Liste keines). Im Dashboard heißt das Nur diese Postfächer.

Payloads

Jedes E-Mail-Ereignis trägt email_id, from, to, subject und created_at, dazu tags, wenn Sie die E-Mail mit Tags gesendet haben.

{
  "type": "email.failed",
  "created_at": "2026-10-13T10:00:02.317Z",
  "data": {
    "email_id": "3f7b2c71-5274-4246-82f3-57bc1563c276",
    "from": "Acme <billing@example.com>",
    "to": ["success@simulator.amazonses.com"],
    "subject": "Your receipt",
    "created_at": "2026-10-13T10:00:02.317Z",
    "failed": { "reason": "domain_not_verified" }
  }
}
failed.reason Was geschehen ist
domain_not_verified Die Absenderdomain war beim Versand der E-Mail nicht verifiziert.
domain_deleted Die Absenderdomain wurde gelöscht, während die E-Mail wartete.
held_for_review_expired Die E-Mail wurde für eine Sicherheitsprüfung zurückgehalten und innerhalb von 7 Tagen nicht freigegeben.
team_suspended Das Team wurde gesperrt und innerhalb von 7 Tagen nach dem Zurückhalten der E-Mail nicht wieder freigeschaltet.
broadcasts_paused Die Newsletter-Versände des Teams wurden pausiert und innerhalb von 7 Tagen nach dem Zurückhalten der E-Mail nicht fortgesetzt.
ses_tenant_paused SES hat den Versand für das Team pausiert und die Pause innerhalb von 7 Tagen nicht aufgehoben.
body_missing, body_unreadable Der gespeicherte Inhalt fehlte oder ließ sich nicht lesen, zum Beispiel weil die E-Mail noch zurückgehalten wurde, als ihr Inhalt die Aufbewahrungsfrist überschritt.
message_rejected Der Mail-Dienst hat die Nachricht abgelehnt, zum Beispiel weil sie einen Virus enthielt.
retries_exhausted Jeder Sendeversuch ist an einem vorübergehenden Fehler gescheitert.
send_interrupted Ein Versand wurde abgebrochen, bevor er bestätigt war, sodass die E-Mail hinausgegangen sein kann oder nicht. Sie wird nicht erneut versucht.
provider_error Jeder andere Fehler, der den Versand gestoppt hat.
{
  "type": "email.suppressed",
  "created_at": "2026-10-14T09:30:00.912Z",
  "data": {
    "email_id": "b10f77bb-a99a-48c9-bd0a-a5d2cb1ba4a1",
    "from": "Acme <hello@example.com>",
    "to": ["success@simulator.amazonses.com"],
    "subject": "Your trial ends tomorrow",
    "created_at": "2026-10-14T09:30:00.912Z",
    "suppressed": {
      "type": "OnAccountSuppressionList",
      "message": "The recipient is on your suppression list.",
      "reason": "recipient_suppressed"
    }
  }
}
suppressed.reason Bedeutung
recipient_suppressed Die Adresse steht auf Ihrer Sperrliste.
contact_unsubscribed Der Kontakt ist teamweit abgemeldet.
domain_unsubscribed Der Empfänger hat sich von dieser Absenderdomain abgemeldet.
topic_unsubscribed Der Empfänger hat das Thema der E-Mail abbestellt.
contact_missing, contact_recipient_mismatch Der Kontakt wurde gelöscht oder seine Adresse hat sich geändert, bevor die E-Mail hinausging.
broadcast_missing, topic_missing Der Newsletter-Versand oder das Thema wurde gelöscht, bevor die E-Mail hinausging.
ineligible Jeder andere Grund, aus dem die E-Mail nicht mehr zulässig war.

Werden nur einige Empfänger entfernt, geht die E-Mail an die übrigen, und es wird kein email.suppressed ausgelöst. Das Abbrechen eines Newsletter-Versands löst für die E-Mails, die er stoppt, nichts aus.

Die Signatur verifizieren

Zustellungen folgen dem Schema von Standard Webhooks. Jede Anfrage trägt:

webhook-id: <message id>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 HMAC-SHA256>

Dieselben Werte werden auch als svix-id, svix-timestamp und svix-signature gesendet, sodass ein Handler, der für eine der beiden Header-Familien geschrieben wurde, unverändert funktioniert. Der signierte Inhalt ist {webhook-id}.{webhook-timestamp}.{raw body}.

import { Webhook } from "standardwebhooks";

const wh = new Webhook("whsec_...");
const event = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
});

Verifizieren Sie immer gegen den rohen Anfrage-Body und lehnen Sie alte Zeitstempel ab.

Secrets

Eigenes mitbringen. POST /webhooks akzeptiert signing_secret: whsec_ gefolgt von Base64 aus 24 bis 64 Bytes. Übergeben Sie das Secret, das Ihr Empfänger bereits verwendet, und der Endpunkt funktioniert ohne erneutes Deployment weiter. Alles andere liefert 422.

Rotieren. POST /webhooks/{id}/rotate oder Secret rotieren im Dashboard erstellt ein neues Secret (oder übernimmt das in signing_secret) und gibt es zurück. Für overlap_hours (Standard 24, bis zu 72) signiert auch das alte Secret weiter, sodass jede Zustellung zwei Signaturen trägt und ein Empfänger mit einem der beiden Secrets sie verifiziert. Stellen Sie Ihren Empfänger zu einem beliebigen Zeitpunkt im Zeitfenster um. 0 verwirft das alte Secret sofort, was Sie bei einem geleakten Secret wollen. GET /webhooks/{id} zeigt als previous_secret_expires_at, wann das Zeitfenster endet.

curl -X POST "https://api.billionsend.com/webhooks/$WEBHOOK_ID/rotate" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "overlap_hours": 24 }'

Zustellung und Wiederholungen

Antworten Sie mit einem beliebigen 2xx-Status, und die Zustellung gilt als erfolgreich. Jeder Endpunkt hat eine eigene Warteschlange, die bis zu 50 Anfragen pro Sekunde sendet.

Ein fehlgeschlagener Versuch (kein 2xx, Timeout, Verbindungsfehler) wird nach 5 Sekunden, 5 Minuten, 30 Minuten, 2 Stunden und 5 Stunden wiederholt. Das sind insgesamt sechs Versuche über etwa 7 Stunden 35 Minuten, und eine Zustellung, die auch den sechsten nicht besteht, wird aufgegeben. Ein 429 mit Retry-After-Header wird beachtet (bis zu einer Stunde) und zählt nicht als Versuch. Ein Ereignis, das 24 Stunden nach dem Einreihen noch nicht zugestellt ist, wird verworfen.

Nach 20 Zustellungen in Folge, die alle Versuche ausgeschöpft haben, wird der Endpunkt automatisch deaktiviert (Status auto_disabled) und erhält nichts, bis Sie ihn wieder aktivieren. Ereignisse, die in der Zwischenzeit aufgetreten sind, werden nicht erneut abgespielt. Die Inhaber des Teams erhalten eine E-Mail, wenn Zustellungen zu scheitern beginnen, wenn ein Endpunkt deaktiviert wird und höchstens einmal pro Tag, wenn sein Rückstand älter als sechs Stunden ist.

Die Zustellung erfolgt mindestens einmal, und Ereignisse werden nicht in Reihenfolge zugestellt. Dasselbe Ereignis kann mehrfach eintreffen, und Ereignisse können in einer anderen Reihenfolge ankommen, als sie geschehen sind: Ein email.delivered kann vor dem email.sent derselben E-Mail kommen. Machen Sie Ihren Handler idempotent, mit webhook-id als Schlüssel, und ordnen Sie die Ereignisse einer E-Mail nach dem created_at des Payloads (wann das Ereignis geschah), nie nach dem Eintreffen. Eine Ausnahme: email.failed mit dem Grund send_interrupted ist eine Vermutung, und ein email.sent, email.delivered oder anderes Ergebnis für dieselbe E-Mail ersetzt es, auch wenn dessen created_at früher liegt.

// event: the verified payload; webhookId: the webhook-id header.
if (await alreadyHandled(webhookId)) return; // a repeat delivery
const at = new Date(event.created_at);
const known = await db.emailStatus(event.data.email_id); // { status, at, guess } or null
const newer = !known || at > known.at || known.guess;
if (newer) {
  const guess = event.type === "email.failed" && event.data.failed.reason === "send_interrupted";
  await db.setEmailStatus(event.data.email_id, { status: event.type, at, guess });
}
await markHandled(webhookId);

Zustellprotokoll

Öffnen Sie im Dashboard einen Endpunkt, um jede Zustellung zu sehen: das Ereignis, den Payload, Ihre Antwort und jeden Versuch, 30 Tage lang aufbewahrt. Sie können bei einer Zustellung auf Jetzt erneut versuchen klicken und mit Test-Ereignis senden den Endpunkt ausprobieren. Die Seite zeigt außerdem die Größe der Warteschlange des Endpunkts und wie lange seine älteste Zustellung wartet.

Limits

Free Starter, Pro, Scale
Webhook-Endpunkte pro Team 1 Kein Limit

Über dem Limit liefert POST /webhooks 403 plan_limit_reached. Nach einem Downgrade funktionieren bestehende Endpunkte weiter, Sie können aber keine weiteren hinzufügen. Abonnieren Sie jeden Endpunkt nur für die Ereignisse, die er braucht: Ein Endpunkt auf „alle Ereignisse“ erhält für jeden importierten Kontakt ein contact.created.

War diese Seite hilfreich?