Sign inGet Started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

Verify-events

Een verificatie produceert events voor de sessie en elke afleverpoging. De sessie begint wanneer Bird de verificatie aanmaakt, en converteert wanneer de ontvanger de juiste code invoert. Elke verzending van een verificatiecode levert een poging op één kanaal op, die afgeleverd of niet-afgeleverd kan zijn. Opnieuw verzenden en kanaalfailover voegen pogingen toe aan dezelfde sessie.
EventAsWordt verstuurd wanneer
verify.verification.createdSessieEen verificatie is aangemaakt en de eerste verificatiecode staat in de wachtrij
verify.attempt.sentAfleveringEen verificatiecode is overgedragen aan een kanaal voor bezorging
verify.attempt.deliveredAfleveringHet kanaal heeft bevestigd dat de verificatiecode de ontvanger heeft bereikt
verify.attempt.undeliveredAfleveringHet kanaal kon de verificatiecode niet bij de ontvanger bezorgen
verify.verification.verifiedSessieDe ontvanger heeft de juiste code ingevoerd voordat de verificatie verliep
verify.verification.failedSessieHet bezorgplan is geëindigd met fouten die aangeven dat er geen verificatiecode is verzonden
Een verificatie die niet converteert, verstuurt nooit verify.verification.verified, en de status vertelt je op zichzelf niet waarom. failed wordt gedeeld: een verificatie komt daar terecht zowel wanneer te veel onjuiste verificatiecodes zijn ingediend, met reason attempts_exhausted, als wanneer het bezorgplan eindigt met fouten die aangeven dat er geen verificatiecode is verzonden, met reason undeliverable. Alleen de tweede verstuurt verify.verification.failed, en dat event bevat altijd reason undeliverable, dus het event is wat de twee gevallen onderscheidt waar de status dat niet kan. Een geldigheidsvenster dat verloopt, resulteert in expired. Noch expired, noch een failed door uitgeputte pogingen verstuurt een eigen event. Een fallback-kanaal maakt een eigen verify.attempt.sent aan, dus één verificatie kan meerdere pogingsreeksen hebben.
De lijst met eventtypen is open: er kunnen in de loop van de tijd nieuwe typen worden toegevoegd, dus behandel een onbekende waarde als een toekomstig event in plaats van een fout.

De eventenvelop

Events komen aan op je webhook-endpoint in de geneste Standard Webhooks-envelop die wordt beschreven in de Webhooks-gids: een type, een timestamp en een typespecifiek data-object. De identiteit van het event zit niet in de body: die staat in de webhook-id HTTP-header, die stabiel is bij herhaalde afleveringen en je deduplicatiesleutel is.
Het data van elk event bevat deze identiteitsbasis:
  • verification_id: de verificatie waar dit event bij hoort, overeenkomend met het id uit POST /v1/verify/verifications
  • workspace_id: de werkruimte die de verificatie heeft aangemaakt
  • to: de ontvangeridentiteit van de verificatie, een object met email en/of phone_number overeenkomend met wat het aanmaakverzoek meegaf. Een enkele verificatiecodepoging rapporteert het ene adres waarnaar het is verzonden in het eigen address-veld
  • metadata: het vrije-vormobject uit het aanmaakverzoek, ongewijzigd teruggegeven, of null wanneer het verzoek er geen bevatte

Sessie-events

verify.verification.created

Wordt verstuurd zodra een verificatie is aangemaakt en de eerste verificatiecode in de wachtrij staat. Voegt channel toe (het kanaal waarover de eerste poging wordt verzonden), status: "pending" en created_at.
Codevoorbeeld
{
  "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

Wordt verstuurd wanneer POST /v1/verify/verifications/check de juiste code bevestigt. Voegt status: "verified", channel toe (het kanaal dat de ingediende code heeft afgeleverd, of null wanneer de verificatie is afgerond zonder een kanaal toe te schrijven) en verified_at.
Codevoorbeeld
{
  "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

Wordt verstuurd wanneer het bezorgplan is uitgeput en de geregistreerde fouten aangeven dat er geen verificatiecode is verzonden. De payload voegt status: "failed", reason: "undeliverable", channel (het laatst geprobeerde kanaal, of null wanneer er geen kanaal is toegewezen), last_attempt_reason en failed_at toe.
channel_unavailable, channel_disabled, channel_restricted en not_billable geven aan dat een poging geen verificatiecode heeft verzonden. Als een poging er mogelijk wel een heeft verzonden, laat een latere bounce, carrier-afwijzing of bezorgtime-out de sessie in afwachting en wordt er geen verify.verification.failed verstuurd. Een eerdere code kan nog steeds worden geverifieerd voordat deze verloopt.
last_attempt_reason gebruikt dezelfde foutredenen als verify.attempt.undelivered. Een not_billable-fout betekent dat de verzending niet in rekening kon worden gebracht; controleer het werkruimtesaldo en of er prijzen beschikbaar zijn voor de bestemming.

Bezorgevents

Elke verificatiecode die Bird verstuurt is één poging. Een opnieuw verzenden of kanaalfailover maakt een nieuwe poging aan tegen dezelfde verification_id, met een eigen bezorgsequentie. Geen enkel event bevat een pogings-ID, en webhook-id groepeert ze niet: het identificeert één bezorging van één event, dus de sent en de delivered voor één poging hebben verschillende waarden. Koppel ze op verification_id, channel en address in tijdstempelvolgorde. Een opnieuw verzenden op hetzelfde kanaal is het geval dat dit doorbreekt, omdat de events dan alleen op tijdstempel verschillen.

verify.attempt.sent

Wordt verstuurd zodra Bird de verificatiecode aan het kanaal heeft overgedragen. Voegt channel, address (het adres waarnaar deze poging is verzonden, een E.164-telefoonnummer of een e-mailadres), from (het verzendadres of -nummer, null wanneer het kanaal geen afzender toont) en sent_at toe.
Codevoorbeeld
{
  "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

Wordt verstuurd wanneer het kanaal bevestigt dat de verificatiecode de ontvanger heeft bereikt. Voegt channel, address, carrier, mcc_mnc (het verwerkende netwerk en de bijbehorende mobile country/network code) en delivered_at toe. De velden carrier en mcc_mnc zijn altijd null voor e-mail, WhatsApp en Telegram. Dit event laat from weg; lees het uit verify.attempt.sent voor dezelfde poging.
Codevoorbeeld
{
  "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

Wordt verstuurd wanneer het kanaal de verificatiecode niet kon bezorgen. Voegt channel, address, reason (een open enum met onder andere carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_restricted, channel_disabled, delivery_timeout en not_billable), error (alleen voor weergave, of null) en failed_at toe. Net als verify.attempt.delivered laat dit event from weg.
Codevoorbeeld
{
  "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" }
  }
}
Een niet-bezorgde poging bij een ontvanger met meer dan één beschikbaar kanaal beëindigt de verificatie niet. Bird gaat verder naar het volgende kanaal in het bezorgplan, dat een eigen verify.attempt.sent krijgt. Een kanaal dat faalt vóór verzending verstuurt verify.attempt.undelivered met reason: "channel_unavailable" en gaat op dezelfde manier verder, net als een kanaal dat geen verificatiecodes bezorgt naar het land van de ontvanger, met reason: "channel_restricted" (zie Landconfiguratie). Die poging heeft geen verify.attempt.sent of later bezorgrapport. Bird verstuurt verify.attempt.undelivered voor elke mislukte poging. Als het plan is uitgeput en de geregistreerde fouten aangeven dat er geen verificatiecode is verzonden, verstuurt het ook verify.verification.failed voor de sessie.
Bezorgrapporten zijn indicatief en niet gegarandeerd. Carriers en mailboxproviders variëren in wat ze bevestigen en hoe snel. In sommige markten komen pogingevents minuten later aan of maken ze geen onderscheid tussen bezorging en acceptatie. Behandel verify.verification.verified als het definitieve signaal dat een ontvanger de code heeft ontvangen en gebruikt.

Webhooks

Abonneer een endpoint op elk verify.*-type via de Webhooks-pagina in het dashboard of via de webhooks-API. De Webhooks-gids behandelt het aanmaken van endpoints, het verifiëren van de Standard Webhooks-handtekening, opnieuw proberen en het opnieuw afspelen van mislukte bezorgingen.

Volgende stappen

PaginaWat het behandelt
Verificaties verzendenDe verzend- en controle-aanroepen, statussen, instellingen en limieten
Webhooks & eventsEndpoint-setup, handtekeningverificatie, opnieuw proberen en opnieuw afspelen
API-referentie: een verificatie aanmakenSchema van het verzendendpoint en foutdetails

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsVerify phone numbers at signupBegrijp het conceptWhat does OTP mean? One-time passwords explainedOntdek de mogelijkheidCustomer verificationVolg het leerpadBuild your first integration
Probeer de oefening en ontvang een implementatieoverzicht