# Webhook einrichten

> Erstellen Sie einen Webhook-Endpunkt, wählen Sie seine Events aus, fügen Sie Payload-Filter hinzu, senden Sie ein Test-Event, aktivieren oder deaktivieren Sie den Webhook oder rotieren Sie sein Secret.

In dieser Anleitung erstellen Sie einen Webhook, schränken ihn auf die Events ein, die Sie brauchen, und prüfen, ob Ihr Endpunkt signierte Anfragen empfängt. Sie können alles in der Weboberfläche oder mit der [Webhooks-API](/de/docs/api-reference/webhooks/) erledigen.

## Voraussetzungen

- Eine öffentliche URL, die `POST`-Anfragen annimmt. HTTPS wird dringend empfohlen. URLs auf `localhost` oder in privaten IP-Bereichen werden abgelehnt; verwenden Sie für die lokale Entwicklung einen Tunnel wie ngrok oder Cloudflare Tunnel.
- Ein Endpunkt, der den unveränderten Anfrage-Body aufbewahrt, damit er [die Signatur verifizieren](/de/docs/webhooks/request-signature/) kann.
- Für die API ein API-Schlüssel mit **Full Access**.
- Ein freier Webhook-Platz. Pay as you go umfasst 3 Endpunkte, Pro 10, Business und Custom je 100.

## Webhook erstellen

**Weboberfläche**

  1. **Webhooks öffnen.** Öffnen Sie **Email API → Webhooks** und wählen Sie **Add webhook**.

  2. **Name und URL eingeben.** Der Name muss im Workspace eindeutig sein, zum Beispiel `Production events`. Die URL ist Ihr Endpunkt, zum Beispiel `https://acme.com/webhooks/emailit`. Wählen Sie **Create**.

  3. **Secret kopieren.** Der Dialog zeigt das Webhook-Secret, das mit `whsec_` beginnt, zusammen mit der Warnung „You can see the webhook secret only once. Store it safely.“ Kopieren Sie es in die Umgebung Ihrer App, zum Beispiel als `EMAILIT_WEBHOOK_SECRET`, und wählen Sie **Done**.

  Ein in der Weboberfläche erstellter Webhook hat alle Event-Typen abonniert. Anschließend öffnet sich der Tab **Settings** des Webhooks, damit Sie die Auswahl einschränken können.

**API**

  Rufen Sie [Webhook erstellen](/de/docs/api-reference/webhooks/create/) auf. Listen Sie die Event-Typen in `events` auf oder setzen Sie `all_events` auf `true`. Die Antwort `201` enthält das `secret`.

```bash
curl https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://acme.com/webhooks/emailit",
    "events": ["email.delivered", "email.bounced", "email.complained"]
  }'
```

  Anders als in der Weboberfläche gelten per API standardmäßig `all_events: false` und eine leere Liste `events`; ein Webhook, der ohne eines von beiden erstellt wird, erhält also nichts. Ein doppelter Name gibt `409` zurück; ist das Endpunkt-Limit Ihres Tarifs erreicht, gibt die API `422` mit `usage.used` und `usage.limit` zurück.

## Events auswählen

Ein Webhook erhält entweder alle Event-Typen oder nur die Typen, die Sie auswählen.

**Weboberfläche**

  Deaktivieren Sie im Tab **Settings** des Webhooks **All events** und wählen Sie dann in der Karte **Events** die gewünschten Typen aus. Die Events sind nach Ressource gruppiert (**Emails**, **Domains**, **Audiences**, **Subscribers**, **Contacts**, **Templates**, **Suppressions**, **Email Verifications**, **Email Verification Lists**), und jede Gruppe hat eine Checkbox **Select all**. Wählen Sie **Save**.

  Die Auswahl listet nicht alle Typen auf, die Emailit sendet. `email.canceled`, `email.held`, `email.unsubscribed`, `email.resubscribed`, `subscriber.resubscribed` und die `campaign.*`-Events erreichen Webhooks, bei denen **All events** aktiviert ist, oder Sie fügen sie per API zur Liste hinzu. Die Gruppe **Deprecated** enthält alte Event-Namen, die nicht mehr gesendet werden. Siehe [Event-Typen](/de/docs/webhooks/event-types/).

**API**

  Rufen Sie [Webhook aktualisieren](/de/docs/api-reference/webhooks/update/) auf. `events` ersetzt die gesamte Liste. Wenn Sie `all_events` auf `true` setzen, wird die Liste geleert.

```bash
curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all_events": false, "events": ["email.received", "email.held", "email.canceled"]}'
```

## Events nach Payload filtern

Pro, Business, Custom

Ein Payload-Filter stellt ein Event nur zu, wenn seine Daten Ihren Regeln entsprechen. Filter gelten zusätzlich zur Event-Auswahl: Ein Event muss abonniert sein *und* den Filter erfüllen.

Damit können Sie den Datenverkehr auf mehrere Endpunkte aufteilen, zum Beispiel einen Webhook pro Produktlinie, oder Events verwerfen, die Sie sonst im Code ignorieren würden.

- **Abgleichsmodus:** **All rules match** (`all`) oder **Any rule matches** (`any`).
- **Regeln:** bis zu 25. Jede Regel besteht aus einem Feld, einem Operator und einem Wert.
- **Feld:** ein Pfad mit Punkten in das `data.object` des Events, zum Beispiel `to`, `status`, `meta.plan` oder bei Klick-Events `link.url`. Das Präfix `payload.` ist optional, `payload.from` und `from` sind also gleichbedeutend.
- **Vergleiche beachten die Groß-/Kleinschreibung** und vergleichen Werte als Text, außer `greater_than` und `less_than`, die Zahlen vergleichen.

| Operator | Trifft zu, wenn das Feld |
| --- | --- |
| `equals` / `not_equals` | Genau den Wert hat / nicht genau den Wert hat. |
| `contains` / `not_contains` | Den Wert enthält / nicht enthält. |
| `starts_with` / `ends_with` | Mit dem Wert beginnt / endet. |
| `greater_than` / `less_than` | Eine Zahl größer / kleiner als der Wert ist. |
| `is_set` / `is_not_set` | Einen nicht leeren Wert hat / fehlt oder leer ist. Kein Wert nötig. |
| `in` / `not_in` | Einem der Werte in einem Array entspricht / keinem davon entspricht. Senden Sie das Array per API, wie im Beispiel unten. |

**Weboberfläche**

  Im Tab **Settings** des Webhooks finden Sie die Karte **Filter**. Wählen Sie den Abgleichsmodus, fügen Sie Regeln mit Feld, Operator und Wert hinzu und wählen Sie **Save**. Lassen Sie die Regeln leer, um alle abonnierten Events zuzustellen. Bei Pay as you go ist die Karte gesperrt und zeigt **Upgrade**.

**API**

  Senden Sie `filter` mit [Webhook erstellen](/de/docs/api-reference/webhooks/create/) oder [Webhook aktualisieren](/de/docs/api-reference/webhooks/update/). Setzen Sie den Wert auf `null`, um den Filter zu entfernen. Bei Pay as you go gibt ein Filter `403` mit `"error": "plan_required"` zurück.

```bash
curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": "all",
      "rules": [
        { "field": "to", "operator": "ends_with", "value": "@acme.com" },
        { "field": "meta.plan", "operator": "in", "value": ["pro", "business"] }
      ]
    }
  }'
```

Weitere Beispiele:

| Ziel | Regel |
| --- | --- |
| Nur E-Mails, die an einer bestimmten Adresse eingehen | `to` `equals` `support@inbound.acme.com` |
| Nur eine Absenderdomain | `from` `ends_with` `@billing.acme.com` |
| Nur E-Mails, die Sie mit Metadaten gekennzeichnet haben | `meta.source` `equals` `checkout` |
| Nur Klicks auf Ihre Preisseite | `link.url` `starts_with` `https://acme.com/pricing` |
| Nur E-Mails mit einer Kunden-ID | `meta.customer_id` `is_set` |

> **Felder unterscheiden sich je nach Event-Typ:** Eine Regel auf ein Feld, das ein Event nicht hat, trifft nie zu. E-Mail-Status-Events haben `to` und `from` auf oberster Ebene, Klick- und Lade-Events verschachteln sie dagegen als `email.rcpt_to` und `email.mail_from`, und Kontakt-Events haben `email`. Mit **All rules match** verwirft ein Webhook, der auf `to` filtert, stillschweigend jeden Klick. Verwenden Sie getrennte Webhooks für jede Art von Event oder **Any rule matches** mit einer Regel pro Struktur. Prüfen Sie die Feldnamen in der [Event-Referenz](/de/docs/webhooks/event-types/).

Wechselt ein Workspace zu Pay as you go, bleiben bestehende Filter gespeichert, werden aber ignoriert, und alle abonnierten Events werden zugestellt.

## Test-Event senden

Ein Test sendet sofort ein Beispiel-Event per POST an Ihre URL, signiert mit dem aktuellen Secret des Webhooks. Abonnierte Events und Filter werden ignoriert, die Anfrage wird nicht wiederholt und erscheint nicht im Tab **Requests**. Jeder Webhook erlaubt 5 Tests pro Minute.

**Weboberfläche**

  Öffnen Sie auf der Webhook-Seite das Aktionsmenü (**…**) und wählen Sie **Send test**. Wählen Sie einen Event-Typ und dann **Send test**. Der Dialog zeigt „Your endpoint returned 200“ (oder den Status, den Ihr Endpunkt zurückgegeben hat) und den Antwort-Body. „Could not reach the endpoint“ bedeutet, dass die Anfrage keine HTTP-Antwort erhalten hat, zum Beispiel wegen eines DNS-Fehlers, eines Timeouts oder eines Redirects.

**API**

  Rufen Sie [Test-Event senden](/de/docs/api-reference/webhooks/test/) mit einem beliebigen Event-Typ auf.

```bash
curl https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/test \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "email.delivered"}'
```

  Die Antwort enthält `ok`, `status_code`, `body` (die Antwort Ihres Endpunkts, bis zu 2.000 Zeichen), `type` und den gesendeten `payload`.

Test-Events verwenden Beispieldaten mit einer `event_id`, die mit `evt_test_` beginnt, und ihre Struktur kann leicht von echten Events abweichen. Richten Sie Ihren Handler nach der [Event-Referenz](/de/docs/webhooks/event-types/) aus und prüfen Sie ihn mit einem echten Versand.

## Webhook aktivieren oder deaktivieren

Deaktivieren Sie einen Webhook, um Zustellungen anzuhalten, ohne seine Einstellungen zu verlieren, zum Beispiel während einer Wartung.

- **Weboberfläche:** Öffnen Sie das Aktionsmenü und wählen Sie **Disable webhook** oder **Enable webhook**. Die Webhook-Seite zeigt den Status **Enabled** oder **Disabled**.
- **API:** Rufen Sie [Webhook aktualisieren](/de/docs/api-reference/webhooks/update/) mit `{"enabled": false}` oder `{"enabled": true}` auf.

Solange ein Webhook deaktiviert ist, werden keine neuen Events für ihn in die Warteschlange gestellt, und Anfragen, die bereits auf eine Wiederholung warten, werden angehalten. Events, die eintreten, während er deaktiviert ist, werden nicht nachträglich zugestellt; lesen Sie sie bei Bedarf mit der [Events-API](/de/docs/logs/events/#reconcile-missed-webhook-events). Emailit deaktiviert Webhooks außerdem automatisch nach 3 Tagen mit Fehlschlägen; siehe [Wiederholungen und Fehlschläge](/de/docs/webhooks/retries-and-failures/).

Wenn Sie einen Webhook löschen, werden alle seine ausstehenden Events verworfen.

## Secret rotieren

Rotieren Sie das Secret, wenn es möglicherweise offengelegt wurde, oder routinemäßig zur Vorsorge.

- **Weboberfläche:** Öffnen Sie das Aktionsmenü, wählen Sie **Webhook secret** und dann **Reset**. Das neue Secret wird einmal angezeigt.
- **API:** Rufen Sie [Signatur-Secret rotieren](/de/docs/api-reference/webhooks/reset-secret/) auf. Die Antwort enthält das neue `secret`. Auch [Webhook abrufen](/de/docs/api-reference/webhooks/get/) gibt das aktuelle Secret zurück.

Das alte Secret funktioniert sofort nicht mehr, und jede Anfrage ab diesem Zeitpunkt, auch Wiederholungen älterer Events, wird mit dem neuen signiert. Um zu rotieren, ohne Anfragen abzulehnen, lassen Sie Ihren Endpunkt für einige Minuten beide Secrets akzeptieren, setzen Sie das Secret zurück, stellen Sie den neuen Wert bereit und entfernen Sie dann den alten.

## Ergebnis prüfen

1. Senden Sie ein Test-Event und prüfen Sie, ob Ihr Endpunkt `2xx` zurückgibt.
2. Senden Sie eine echte E-Mail oder lösen Sie das Event aus, das Sie abonniert haben.
3. Im Tab **Requests** des Webhooks zeigt die Anfrage **Delivered**. Der Zeitpunkt **Last used** des Webhooks wird aktualisiert.

## Siehe auch

  - [Signaturen verifizieren](/de/docs/webhooks/request-signature/)
  - [Webhook-Anfragen](/de/docs/webhooks/webhook-requests/)
  - [Event-Typen](/de/docs/webhooks/event-types/)
  - [Wiederholungen und Fehlschläge](/de/docs/webhooks/retries-and-failures/)

---
Quelle: https://emailit.com/de/docs/webhooks/set-up/