Verify-Events

Eine Verifizierung erzeugt Events für ihre Session und jeden Zustellversuch. Die Session beginnt, wenn Bird die Verifizierung erstellt, und wird abgeschlossen, wenn der Empfänger den richtigen Code eingibt. Jeder Bestätigungscode-Versand erzeugt einen Versuch auf einem Kanal, der zugestellt oder nicht zugestellt werden kann. Erneute Sendungen und Kanal-Failover fügen derselben Session weitere Versuche hinzu.

Event	Achse	Wird ausgelöst, wenn
verify.verification.created	Session	Eine Verifizierung wird erstellt und der erste Bestätigungscode zum Senden eingereiht
verify.attempt.sent	Zustellung	Ein Bestätigungscode wurde an einen Kanal zur Zustellung übergeben
verify.attempt.delivered	Zustellung	Der Kanal hat bestätigt, dass der Bestätigungscode den Empfänger erreicht hat
verify.attempt.undelivered	Zustellung	Der Kanal konnte den Bestätigungscode nicht an den Empfänger zustellen
verify.verification.verified	Session	Der Empfänger hat den richtigen Code eingegeben, bevor die Verifizierung abgelaufen ist
verify.verification.failed	Session	Der Zustellplan endete mit Fehlern, die darauf hinweisen, dass kein Bestätigungscode gesendet wurde

Eine Verifizierung, die nicht konvertiert, löst niemals verify.verification.verified aus, und ihr Status allein verrät Ihnen nicht den Grund. failed ist mehrdeutig: Eine Verifizierung landet dort sowohl wenn zu viele falsche Bestätigungscodes eingereicht wurden, mit reason attempts_exhausted, als auch wenn der Zustellplan mit Fehlern endet, die darauf hinweisen, dass kein Bestätigungscode gesendet wurde, mit reason undeliverable. Nur der zweite Fall löst verify.verification.failed aus, und dieses Event trägt immer reason undeliverable, sodass das Event die beiden Fälle dort unterscheidet, wo der Status es nicht kann. Ein abgelaufenes Gültigkeitsfenster wird zu expired aufgelöst. Weder expired noch ein durch erschöpfte Versuche ausgelöstes failed erzeugt ein eigenes Event. Ein Fallback-Kanal erstellt sein eigenes verify.attempt.sent, sodass eine Verifizierung mehrere Versuchssequenzen haben kann.

Die Liste der Event-Typen ist offen: Neue Typen können im Laufe der Zeit hinzukommen. Behandeln Sie einen unbekannten Wert als zukünftiges Event und nicht als Fehler.

Der Event-Envelope

Events treffen an Ihrem Webhook-Endpoint im verschachtelten Standard-Webhooks-Envelope ein, der im Webhooks-Leitfaden beschrieben ist: ein type, ein timestamp und ein typspezifisches data-Objekt. Die Identität des Events steht nicht im Body: Sie befindet sich im webhook-id-HTTP-Header, der bei erneuten Zustellversuchen desselben Events stabil bleibt und Ihr Deduplizierungsschlüssel ist.

Das data jedes Events enthält diese Identitätsbasis:

verification_id: die Verifizierung, zu der dieses Event gehört, passend zur id aus POST /v1/verify/verifications
workspace_id: der Workspace, der die Verifizierung erstellt hat
to: die Empfängeridentität der Verifizierung, ein Objekt mit email und/oder phone_number, passend zu den Angaben im Erstellungs-Request. Ein einzelner Bestätigungscode-Versuch gibt die eine Adresse, an die er gesendet wurde, in seinem eigenen address-Feld an
metadata: das Freiformat-Objekt aus dem Erstellungs-Request, unverändert zurückgegeben, oder null, wenn der Request keines enthielt

Session-Events

verify.verification.created

Wird ausgelöst, sobald eine Verifizierung erstellt und ihr erster Bestätigungscode eingereiht wird. Fügt channel (den Kanal, über den der erste Versuch gesendet wird), status: "pending" und created_at hinzu.

Codebeispiel

{
  "type": "verify.verification.created",
  "timestamp": "2026-07-23T14:45:58Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "channel": "sms",
    "to": { "phone_number": "+14155550100" },
    "status": "pending",
    "created_at": "2026-07-23T14:45:58Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

verify.verification.verified

Wird ausgelöst, wenn POST /v1/verify/verifications/check den richtigen Code bestätigt. Fügt status: "verified", channel (der Kanal, der den eingereichten Code zugestellt hat, oder null, wenn die Verifizierung ohne Kanalzuordnung abgeschlossen wurde) und verified_at hinzu.

Codebeispiel

{
  "type": "verify.verification.verified",
  "timestamp": "2026-07-23T14:46:38Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "to": { "phone_number": "+14155550100" },
    "status": "verified",
    "channel": "sms",
    "verified_at": "2026-07-23T14:46:38Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

verify.verification.failed

Wird ausgelöst, wenn der Zustellplan erschöpft ist und die aufgezeichneten Fehler darauf hinweisen, dass kein Bestätigungscode gesendet wurde. Die Payload enthält zusätzlich status: "failed", reason: "undeliverable", channel (der zuletzt versuchte Kanal, oder null, wenn keiner zugeordnet wurde), last_attempt_reason und failed_at.

channel_unavailable, channel_disabled, channel_restricted und not_billable zeigen an, dass ein Versuch keinen Bestätigungscode gesendet hat. Falls ein Versuch möglicherweise einen gesendet hat, hält ein späterer Bounce, eine Carrier-Ablehnung oder ein Zustellungs-Timeout die Session offen und löst kein verify.verification.failed aus. Ein zuvor gesendeter Code kann weiterhin vor Ablauf verifiziert werden.

last_attempt_reason verwendet dieselben Fehlergründe wie verify.attempt.undelivered. Ein not_billable-Fehler bedeutet, dass der Versand nicht abgerechnet werden konnte; prüfen Sie das Workspace-Guthaben und ob für das Ziel eine Preisgestaltung verfügbar ist.

Zustellungs-Events

Jeder Bestätigungscode, den Bird sendet, ist ein Versuch. Ein erneutes Senden oder Kanal-Failover erzeugt einen weiteren Versuch gegen dieselbe verification_id, mit einer eigenen Zustellsequenz. Kein Event enthält einen Versuchsbezeichner, und webhook-id gruppiert sie nicht: Es identifiziert eine Zustellung eines Events, sodass das sent und das delivered für einen einzelnen Versuch unterschiedliche Werte haben. Ordnen Sie sie über verification_id, channel und address in zeitlicher Reihenfolge zu. Ein erneutes Senden über denselben Kanal ist der Fall, bei dem dies nicht funktioniert, da sich die Events nur durch den Zeitstempel unterscheiden.

verify.attempt.sent

Wird ausgelöst, sobald Bird den Bestätigungscode an den Kanal übergeben hat. Enthält zusätzlich channel, address (die einzelne Adresse, an die dieser Versuch gesendet wurde, eine E.164-Telefonnummer oder eine E-Mail-Adresse), from (die Absenderadresse oder -nummer, null, wenn der Kanal keinen Absender offenlegt) und sent_at.

Codebeispiel

{
  "type": "verify.attempt.sent",
  "timestamp": "2026-07-23T14:45:59Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "to": { "phone_number": "+14155550100" },
    "channel": "sms",
    "address": "+14155550100",
    "from": "29999",
    "sent_at": "2026-07-23T14:45:59Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

verify.attempt.delivered

Wird ausgelöst, wenn der Kanal bestätigt, dass der Bestätigungscode den Empfänger erreicht hat. Enthält zusätzlich channel, address, carrier, mcc_mnc (das verarbeitende Netz und seinen Mobile Country/Network Code) und delivered_at. Die Felder carrier und mcc_mnc sind bei E-Mail, WhatsApp und Telegram immer null. Dieses Event enthält kein from; lesen Sie es aus verify.attempt.sent für denselben Versuch.

Codebeispiel

{
  "type": "verify.attempt.delivered",
  "timestamp": "2026-07-23T14:46:03Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "to": { "phone_number": "+14155550100" },
    "channel": "sms",
    "address": "+14155550100",
    "carrier": "Example Wireless",
    "mcc_mnc": "310260",
    "delivered_at": "2026-07-23T14:46:03Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

verify.attempt.undelivered

Wird ausgelöst, wenn der Kanal den Bestätigungscode nicht zustellen konnte. Enthält zusätzlich channel, address, reason (ein offenes Enum mit carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_restricted, channel_disabled, delivery_timeout und not_billable), error (nur zur Anzeige gedachtes Detail, oder null) und failed_at. Wie verify.attempt.delivered enthält dieses Event kein from.

Codebeispiel

{
  "type": "verify.attempt.undelivered",
  "timestamp": "2026-07-23T14:46:04Z",
  "data": {
    "verification_id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "to": { "phone_number": "+14155550100" },
    "channel": "sms",
    "address": "+14155550100",
    "reason": "carrier_rejected",
    "error": "Carrier rejected the message before delivery",
    "failed_at": "2026-07-23T14:46:04Z",
    "metadata": { "user_id": "usr_4821" }
  }
}

Ein fehlgeschlagener Zustellversuch bei einem Empfänger mit mehr als einem verfügbaren Kanal beendet die Verifizierung nicht. Bird wechselt zum nächsten Kanal im Zustellplan, der sein eigenes verify.attempt.sent erhält. Ein Kanal, der vor dem Senden fehlschlägt, löst verify.attempt.undelivered mit reason: "channel_unavailable" aus und wechselt auf dieselbe Weise, ebenso ein Kanal, der keine Bestätigungscodes in das Land des Empfängers zustellt, mit reason: "channel_restricted" (siehe Länderkonfiguration). Dieser Versuch hat kein verify.attempt.sent und keinen späteren Zustellbericht. Bird löst verify.attempt.undelivered für jeden fehlgeschlagenen Versuch aus. Wenn der Plan erschöpft ist und die aufgezeichneten Fehler darauf hinweisen, dass kein Bestätigungscode gesendet wurde, wird zusätzlich verify.verification.failed für die Session ausgelöst.

Zustellberichte sind Hinweise, keine Garantie. Carrier und Mailbox-Provider unterscheiden sich darin, was sie bestätigen und wie schnell. In manchen Märkten treffen Versuch-Events erst Minuten später ein oder unterscheiden nicht zwischen Zustellung und Annahme. Behandeln Sie verify.verification.verified als das definitive Signal, dass ein Empfänger seinen Code erhalten und verwendet hat.

Webhooks

Abonnieren Sie einen Endpoint für jeden verify.*-Typ über die Seite Webhooks im Dashboard oder über die Webhooks-API. Der Webhooks-Leitfaden behandelt das Erstellen von Endpoints, das Verifizieren der Standard-Webhooks-Signatur, Wiederholungsversuche und das erneute Abspielen fehlgeschlagener Zustellungen.

Nächste Schritte

Seite	Inhalt
Verifizierungen senden	Sende- und Prüfaufrufe, Status, Einstellungen und Limits
Webhooks & Events	Endpoint-Einrichtung, Signaturverifizierung, Wiederholungsversuche und Replay
API-Referenz: Verifizierung erstellen	Sende-Endpoint-Schema und Fehlerdetails

Verwandte Ressourcen