Zdarzenia Verify

Weryfikacja generuje zdarzenia dla swojej sesji i każdej próby dostarczenia. Sesja rozpoczyna się, gdy Bird tworzy weryfikację, a konwertuje, gdy odbiorca wprowadzi poprawny kod. Każde wysłanie kodu weryfikacyjnego tworzy próbę na jednym kanale, która może zakończyć się dostarczeniem lub niedostarczeniem. Ponowne wysyłki i przełączenie na kanał zapasowy dodają próby do tej samej sesji.

Zdarzenie	Oś	Występuje, gdy
verify.verification.created	Sesja	Weryfikacja została utworzona, a pierwszy kod weryfikacyjny został kolejkowany do wysyłki
verify.attempt.sent	Dostarczenie	Kod weryfikacyjny został przekazany kanałowi do dostarczenia
verify.attempt.delivered	Dostarczenie	Kanał potwierdził, że kod weryfikacyjny dotarł do odbiorcy
verify.attempt.undelivered	Dostarczenie	Kanał nie mógł dostarczyć kodu weryfikacyjnego do odbiorcy
verify.verification.verified	Sesja	Odbiorca przesłał poprawny kod przed wygaśnięciem weryfikacji
verify.verification.failed	Sesja	Plan dostarczania zakończył się błędami wskazującymi, że żaden kod weryfikacyjny nie został wysłany

Weryfikacja, która nie zakończy się konwersją, nigdy nie emituje verify.verification.verified, a sam jej status nie mówi dlaczego. failed jest współdzielony: weryfikacja trafia tam zarówno wtedy, gdy przesłano zbyt wiele niepoprawnych kodów weryfikacyjnych, z reason attempts_exhausted, jak i wtedy, gdy plan dostarczania kończy się błędami wskazującymi, że żaden kod weryfikacyjny nie został wysłany, z reason undeliverable. Tylko drugi przypadek emituje verify.verification.failed, a to zdarzenie zawsze zawiera reason undeliverable, więc to zdarzenie rozróżnia te dwa przypadki tam, gdzie status nie może. Upłynięcie okna ważności kończy się statusem expired. Ani expired, ani wyczerpanie prób failed nie emituje własnego zdarzenia. Kanał zapasowy tworzy własne verify.attempt.sent, więc jedna weryfikacja może mieć wiele sekwencji prób.

Lista typów zdarzeń jest otwarta: nowe typy mogą być dodawane z czasem, więc traktuj nierozpoznaną wartość jako przyszłe zdarzenie, a nie błąd.

Koperta zdarzenia

Zdarzenia docierają do Twojego endpointu webhooka w zagnieżdżonej kopercie Standard Webhooks opisanej w przewodniku po webhookach: type, timestamp oraz obiekt data specyficzny dla danego typu. Tożsamość zdarzenia nie znajduje się w ciele żądania: jest przekazywana w nagłówku webhook-id HTTP, który pozostaje stały między ponownymi próbami tego samego dostarczenia i stanowi Twój klucz deduplikacji.

Pole data każdego zdarzenia zawiera tę bazę tożsamości:

verification_id: weryfikacja, do której należy to zdarzenie, odpowiadająca id z POST /v1/verify/verifications
workspace_id: obszar roboczy, który utworzył weryfikację
to: tożsamość odbiorcy weryfikacji, obiekt z email i/lub phone_number odpowiadającymi wartościom z żądania tworzenia. Pojedyncza próba wysyłki kodu weryfikacyjnego podaje adres, na który została wysłana, we własnym polu address
metadata: dowolny obiekt z żądania tworzenia, zwrócony bez zmian, lub null, gdy żądanie go nie zawierało

Zdarzenia sesji

verify.verification.created

Występuje natychmiast po utworzeniu weryfikacji i umieszczeniu pierwszego kodu weryfikacyjnego w kolejce. Dodaje channel (kanał, przez który wychodzi pierwsza próba), status: "pending" oraz created_at.

Przykład kodu

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

Występuje, gdy POST /v1/verify/verifications/check potwierdzi poprawny kod. Dodaje status: "verified", channel (kanał, przez który dostarczono przesłany kod, lub null, gdy weryfikacja została rozwiązana bez przypisania kanału) oraz verified_at.

Przykład kodu

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

Występuje, gdy plan dostarczania został wyczerpany, a zarejestrowane błędy wskazują, że żaden kod weryfikacyjny nie został wysłany. Payload zawiera dodatkowo status: "failed", reason: "undeliverable", channel (ostatni wypróbowany kanał lub null, gdy żaden nie został przypisany), last_attempt_reason i failed_at.

channel_unavailable, channel_disabled, channel_restricted i not_billable wskazują, że próba nie wysłała kodu weryfikacyjnego. Jeśli próba mogła go wysłać, późniejszy bounce, odrzucenie przez operatora lub przekroczenie czasu dostarczania pozostawia sesję w stanie oczekiwania i nie emituje verify.verification.failed. Wcześniejszy kod nadal może zostać zweryfikowany przed wygaśnięciem.

last_attempt_reason używa tych samych przyczyn błędów co verify.attempt.undelivered. Błąd not_billable oznacza, że wysyłka nie mogła zostać naliczona; sprawdź saldo obszaru roboczego i czy cennik jest dostępny dla danego kierunku.

Zdarzenia dostarczania

Każdy kod weryfikacyjny wysyłany przez Bird to jedna próba. Ponowna wysyłka lub przełączenie na inny kanał tworzy kolejną próbę w ramach tej samej sesji verification_id, z własną sekwencją dostarczania. Żadne zdarzenie nie zawiera identyfikatora próby, a webhook-id nie zgrupuje ich: identyfikuje jedno dostarczenie jednego zdarzenia, więc sent i delivered dla pojedynczej próby mają różne wartości. Łącz je po verification_id, channel i address w kolejności znaczników czasu. Ponowna wysyłka na tym samym kanale jest przypadkiem, który to uniemożliwia, ponieważ jej zdarzenia różnią się tylko znacznikiem czasu.

verify.attempt.sent

Występuje, gdy Bird przekazał kod weryfikacyjny kanałowi. Dodaje channel, address (pojedynczy adres, na który wysłano tę próbę, numer telefonu E.164 lub adres e-mail), from (adres lub numer nadawcy, null, gdy kanał nie ujawnia nadawcy) i sent_at.

Przykład kodu

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

Występuje, gdy kanał potwierdzi, że kod weryfikacyjny dotarł do odbiorcy. Dodaje channel, address, carrier, mcc_mnc (obsługująca sieć i jej kod kraju/sieci mobilnej) i delivered_at. Pola carrier i mcc_mnc mają zawsze wartość null dla e-maila, WhatsApp i Telegrama. To zdarzenie pomija from; odczytaj je z verify.attempt.sent dla tej samej próby.

Przykład kodu

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

Występuje, gdy kanał nie mógł dostarczyć kodu weryfikacyjnego. Dodaje channel, address, reason (otwarty enum zawierający carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_restricted, channel_disabled, delivery_timeout i not_billable), error (szczegóły wyłącznie do wyświetlenia lub null) i failed_at. Podobnie jak verify.attempt.delivered, to zdarzenie pomija from.

Przykład kodu

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

Niedostarczona próba u odbiorcy z więcej niż jednym dostępnym kanałem nie kończy weryfikacji. Bird przechodzi do następnego kanału w planie dostarczania, który otrzymuje własne verify.attempt.sent. Kanał, który zawiedzie przed wysyłką, emituje verify.attempt.undelivered z reason: "channel_unavailable" i przechodzi dalej w ten sam sposób, podobnie jak kanał, który nie obsługuje kodów weryfikacyjnych w kraju odbiorcy, z reason: "channel_restricted" (zobacz Konfiguracja krajów). Taka próba nie ma verify.attempt.sent ani późniejszego raportu dostarczenia. Bird emituje verify.attempt.undelivered dla każdej nieudanej próby. Jeśli plan zostanie wyczerpany, a zarejestrowane błędy wskazują, że żaden kod weryfikacyjny nie został wysłany, emituje również verify.verification.failed dla sesji.

Raporty dostarczenia mają charakter orientacyjny, a nie gwarantowany. Operatorzy i dostawcy skrzynek pocztowych różnią się tym, co potwierdzają i jak szybko. Na niektórych rynkach zdarzenia prób przychodzą z kilkuminutowym opóźnieniem lub nie odróżniają dostarczenia od przyjęcia. Traktuj verify.verification.verified jako ostateczny sygnał, że odbiorca otrzymał i użył swojego kodu.

Webhooki

Subskrybuj endpoint na dowolny typ verify.* na stronie Webhooks w dashboardzie lub przez API webhooków. Przewodnik po webhookach opisuje tworzenie endpointów, weryfikację podpisu Standard Webhooks, ponawianie i odtwarzanie nieudanych dostarczeń.

Następne kroki

Strona	Co opisuje
Wysyłanie weryfikacji	Wywołania wysyłki i sprawdzania, statusy, ustawienia i limity
Webhooki i zdarzenia	Konfiguracja endpointu, weryfikacja podpisu, ponawianie i odtwarzanie
Dokumentacja API: tworzenie weryfikacji	Schemat endpointu wysyłki i szczegóły błędów

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Obejrzyj przewodnikVerify phone numbers at signup Zrozum koncepcjęWhat does OTP mean? One-time passwords explained Poznaj możliwościCustomer verification Podążaj ścieżką naukiBuild your first integration

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy