Sign inGet Started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

Événements Verify

Une vérification produit des événements pour sa session et chaque tentative de livraison. La session commence lorsque Bird crée la vérification, et se convertit quand le destinataire saisit le bon code. Chaque envoi de code de vérification crée une tentative sur un canal, qui peut aboutir ou échouer. Les renvois et le basculement de canal ajoutent des tentatives à la même session.
ÉvénementAxeSe déclenche quand
verify.verification.createdSessionUne vérification est créée et le premier code de vérification est mis en file d'envoi
verify.attempt.sentLivraisonUn code de vérification a été transmis à un canal pour livraison
verify.attempt.deliveredLivraisonLe canal a confirmé que le code de vérification a atteint le destinataire
verify.attempt.undeliveredLivraisonLe canal n'a pas pu faire parvenir le code de vérification au destinataire
verify.verification.verifiedSessionLe destinataire a soumis le bon code avant l'expiration de la vérification
verify.verification.failedSessionLe plan de livraison s'est terminé avec des échecs indiquant qu'aucun code de vérification n'a été envoyé
Une vérification qui ne convertit pas n'émet jamais verify.verification.verified, et son statut seul ne vous indique pas pourquoi. failed est partagé : une vérification y aboutit aussi bien lorsque trop de codes incorrects ont été soumis, avec reason attempts_exhausted, que lorsque le plan de livraison se termine avec des échecs indiquant qu'aucun code n'a été envoyé, avec reason undeliverable. Seul le second cas émet verify.verification.failed, et cet événement porte toujours reason undeliverable ; c'est donc l'événement qui distingue les deux là où le statut ne le peut pas. Une fenêtre de validité qui expire se résout en expired. Ni expired ni un failed par épuisement des tentatives n'émet d'événement propre. Un canal de repli crée son propre verify.attempt.sent, une même vérification peut donc avoir plusieurs séquences de tentatives.
La liste des types d'événements est ouverte : de nouveaux types peuvent être ajoutés au fil du temps. Traitez donc une valeur non reconnue comme un événement futur plutôt que comme une erreur.

L'enveloppe d'événement

Les événements arrivent à votre endpoint webhook dans l'enveloppe imbriquée Standard Webhooks décrite dans le guide Webhooks : un type, un timestamp et un objet data propre au type. L'identité de l'événement ne se trouve pas dans le corps : elle est portée par l'en-tête webhook-id HTTP, qui est stable d'un réessai à l'autre pour la même livraison et constitue votre clé de déduplication.
Le data de chaque événement porte cette base d'identité :
  • verification_id : la vérification à laquelle cet événement appartient, correspondant au id de POST /v1/verify/verifications
  • workspace_id : l'espace de travail qui a créé la vérification
  • to : l'identité du destinataire de la vérification, un objet avec email et/ou phone_number correspondant à ce que la requête de création a fourni. Une tentative de code de vérification individuelle indique l'adresse unique utilisée dans son propre champ address
  • metadata : l'objet libre issu de la requête de création, renvoyé tel quel, ou null si la requête n'en contenait pas

Événements de session

verify.verification.created

Se déclenche dès qu'une vérification est créée et que son premier code de vérification est mis en file d'attente. Ajoute channel (le canal sur lequel la première tentative est envoyée), status: "pending" et created_at.
Exemple de code
{
  "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

Se déclenche quand POST /v1/verify/verifications/check confirme le bon code. Ajoute status: "verified", channel (le canal qui a livré le code soumis, ou null quand la vérification s'est résolue sans attribuer de canal) et verified_at.
Exemple de code
{
  "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

Se déclenche lorsque le plan de livraison est épuisé et que les échecs enregistrés indiquent qu'aucun code de vérification n'a été envoyé. Le payload ajoute status: "failed", reason: "undeliverable", channel (le dernier canal essayé, ou null quand aucun n'a été attribué), last_attempt_reason et failed_at.
channel_unavailable, channel_disabled, channel_restricted et not_billable indiquent qu'une tentative n'a pas envoyé de code de vérification. Si une tentative a pu en envoyer un, un rebond ultérieur, un rejet par l'opérateur ou un délai de livraison dépassé laisse la session en attente et n'émet aucun verify.verification.failed. Un code émis précédemment peut encore aboutir avant son expiration.
last_attempt_reason utilise les mêmes raisons d'échec que verify.attempt.undelivered. Un échec not_billable signifie que l'envoi n'a pas pu être facturé ; vérifiez le solde de l'espace de travail et la disponibilité de la tarification pour la destination.

Événements de livraison

Chaque code de vérification envoyé par Bird constitue une tentative. Un renvoi ou un basculement de canal crée une nouvelle tentative sur la même verification_id, avec sa propre séquence de livraison. Aucun événement ne porte d'identifiant de tentative, et webhook-id ne les regroupe pas : il identifie une livraison d'un événement, donc le sent et le delivered d'une même tentative portent des valeurs différentes. Associez-les par verification_id, channel et address dans l'ordre chronologique. Un renvoi sur le même canal est le cas qui met cette méthode en échec, car ses événements ne diffèrent que par l'horodatage.

verify.attempt.sent

Se déclenche dès que Bird a transmis le code de vérification au canal. Ajoute channel, address (l'adresse unique à laquelle cette tentative a été envoyée, un numéro de téléphone E.164 ou une adresse e-mail), from (l'adresse ou le numéro d'envoi, null quand le canal n'expose pas d'expéditeur) et sent_at.
Exemple de code
{
  "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

Se déclenche lorsque le canal confirme que le code de vérification a atteint le destinataire. Ajoute channel, address, carrier, mcc_mnc (le réseau de traitement et son code pays/réseau mobile) et delivered_at. Les champs carrier et mcc_mnc valent toujours null pour l'e-mail, WhatsApp et Telegram. Cet événement omet from ; lisez-le depuis verify.attempt.sent pour la même tentative.
Exemple de code
{
  "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

Se déclenche lorsque le canal n'a pas pu livrer le code de vérification. Ajoute channel, address, reason (une énumération ouverte incluant carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_restricted, channel_disabled, delivery_timeout et not_billable), error (détail d'affichage uniquement, ou null) et failed_at. Comme verify.attempt.delivered, cet événement omet from.
Exemple de code
{
  "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" }
  }
}
Une tentative non livrée chez un destinataire disposant de plusieurs canaux ne met pas fin à la vérification. Bird passe au canal suivant du plan de livraison, qui obtient son propre verify.attempt.sent. Un canal qui échoue avant l'envoi émet verify.attempt.undelivered avec reason: "channel_unavailable" et passe au suivant de la même façon, tout comme un canal qui ne transmet pas de codes de vérification vers le pays du destinataire, avec reason: "channel_restricted" (voir Configuration par pays). Cette tentative n'a pas de verify.attempt.sent ni de rapport de livraison ultérieur. Bird émet verify.attempt.undelivered pour chaque tentative échouée. Si le plan est épuisé et que les échecs enregistrés indiquent qu'aucun code n'a été envoyé, il émet également verify.verification.failed pour la session.
Les rapports de livraison sont indicatifs et non garantis. Les opérateurs et fournisseurs de messagerie varient dans ce qu'ils confirment et à quelle vitesse. Sur certains marchés, les événements de tentative arrivent plusieurs minutes plus tard ou ne distinguent pas la livraison de l'acceptation. Considérez verify.verification.verified comme le signal définitif qu'un destinataire a reçu et utilisé son code.

Webhooks

Abonnez un endpoint à n'importe quel type verify.* depuis la page Webhooks du tableau de bord ou via l'API webhooks. Le guide Webhooks couvre la création d'endpoints, la vérification de la signature Standard Webhooks, les réessais et le rejeu des livraisons échouées.

Étapes suivantes

PageContenu couvert
Envoyer des vérificationsLes appels d'envoi et de vérification, statuts, paramètres et limites
Webhooks et événementsConfiguration des endpoints, vérification de la signature, réessais et rejeu
Référence API : créer une vérificationSchéma de l'endpoint d'envoi et détails des erreurs

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideVerify phone numbers at signupComprendre le conceptWhat does OTP mean? One-time passwords explainedExplorer la fonctionnalitéCustomer verificationSuivre le parcours d'apprentissageBuild your first integration
Essayez la pratique et obtenez un guide d'implémentation