Webhook einrichten

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 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 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

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"]
  }'

Events auswählen

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

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

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.

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:

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.

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"}'

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 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 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. Emailit deaktiviert Webhooks außerdem automatisch nach 3 Tagen mit Fehlschlägen; siehe Wiederholungen und Fehlschläge.

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 auf. Die Antwort enthält das neue secret. Auch Webhook abrufen 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