---
title: Webhooks
description: Signierte Ereigniszustellungen an Ihren Endpunkt, mit Wiederholungen und einem Zustellprotokoll.
seo:
  title: E-Mail-Webhooks
ai:
  exclude: true
---

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](/docs/de/sdks) verifizieren Zustellungen mit `verifyWebhook` (Node.js) und `verify_webhook` (Python).

```sh
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](/docs/de/concepts/suppressions)), `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](/docs/de/concepts/domains)). |
| `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](/docs/de/receiving) 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](/docs/de/concepts/unsubscribes).

### Postfach-Ereignisse

[Postfächer](/docs/de/inboxes) 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.

```json title="email.failed"
{
  "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. |

```json title="email.suppressed"
{
  "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](https://www.standardwebhooks.com). 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}`.

```ts
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.

```sh
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.

```ts
// 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`.
