Sign inGet Started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Eventos do Verify

Uma verificação produz eventos para sua sessão e para cada tentativa de entrega. A sessão começa quando Bird cria a verificação e converte quando o destinatário informa o código correto. Cada envio de código de verificação cria uma tentativa em um canal, que pode ser entregue ou não entregue. Reenvios e failover de canal adicionam tentativas à mesma sessão.
EventoEixoDispara quando
verify.verification.createdSessãoUma verificação é criada e o primeiro código de verificação é enfileirado para envio
verify.attempt.sentEntregaUm código de verificação foi entregue a um canal para envio
verify.attempt.deliveredEntregaO canal confirmou que o código de verificação chegou ao destinatário
verify.attempt.undeliveredEntregaO canal não conseguiu entregar o código de verificação ao destinatário
verify.verification.verifiedSessãoO destinatário enviou o código correto antes de a verificação expirar
verify.verification.failedSessãoO plano de entrega terminou com falhas indicando que nenhum código de verificação foi enviado
Uma verificação que não converte nunca emite verify.verification.verified, e seu status sozinho não diz o motivo. failed é compartilhado: uma verificação chega a esse estado tanto quando códigos de verificação incorretos demais foram enviados, com reason attempts_exhausted, quanto quando o plano de entrega termina com falhas indicando que nenhum código foi enviado, com reason undeliverable. Só o segundo caso emite verify.verification.failed, e esse evento sempre carrega reason undeliverable, então é o evento que diferencia os dois onde o status não consegue. Uma janela de validade que expira resolve para expired. Nem expired nem um failed por tentativas esgotadas emite um evento próprio. Um canal de fallback cria seu próprio verify.attempt.sent, então uma verificação pode ter múltiplas sequências de tentativas.
A lista de tipos de evento é aberta: novos tipos podem ser adicionados com o tempo, então trate um valor não reconhecido como um evento futuro em vez de um erro.

O envelope do evento

Os eventos chegam ao seu endpoint de webhook no envelope aninhado Standard Webhooks descrito no Guia de webhooks: um type, um timestamp e um objeto data específico do tipo. A identidade do evento não está no corpo: ela é transportada no header webhook-id HTTP, que permanece estável entre tentativas de entrega do mesmo evento e é a sua chave de deduplicação.
O data de cada evento carrega esta base de identidade:
  • verification_id: a verificação à qual este evento pertence, correspondendo ao id de POST /v1/verify/verifications
  • workspace_id: o espaço de trabalho que criou a verificação
  • to: a identidade do destinatário da verificação, um objeto com email e/ou phone_number correspondendo ao que a solicitação de criação forneceu. Uma tentativa individual de código de verificação informa o endereço para o qual foi enviada no seu próprio campo address
  • metadata: o objeto de formato livre da solicitação de criação, ecoado sem alterações, ou null quando a solicitação não incluiu nenhum

Eventos de sessão

verify.verification.created

Dispara assim que uma verificação é criada e seu primeiro código de verificação é enfileirado. Adiciona channel (o canal pelo qual a primeira tentativa está sendo enviada), status: "pending" e created_at.
Exemplo de código
{
  "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

Dispara quando POST /v1/verify/verifications/check confirma o código correto. Adiciona status: "verified", channel (o canal que entregou o código enviado, ou null quando a verificação foi resolvida sem atribuir um canal) e verified_at.
Exemplo de código
{
  "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

Dispara quando o plano de entrega se esgota e as falhas registradas indicam que nenhum código de verificação foi enviado. O payload adiciona status: "failed", reason: "undeliverable", channel (o último canal tentado, ou null quando nenhum foi atribuído), last_attempt_reason e failed_at.
channel_unavailable, channel_disabled, channel_restricted e not_billable indicam que uma tentativa não enviou um código de verificação. Se uma tentativa pode ter enviado um, um bounce posterior, rejeição da operadora ou timeout de entrega mantém a sessão pendente e não emite verify.verification.failed. Um código anterior ainda pode verificar antes de expirar.
last_attempt_reason usa os mesmos motivos de falha que verify.attempt.undelivered. Uma falha not_billable significa que o envio não pôde ser cobrado; verifique o saldo do espaço de trabalho e se há precificação disponível para o destino.

Eventos de entrega

Cada código de verificação que Bird envia é uma tentativa. Um reenvio ou failover de canal cria outra tentativa contra a mesma verification_id, com sua própria sequência de entrega. Nenhum evento carrega um identificador de tentativa, e webhook-id não os agrupa: ele identifica uma entrega de um evento, então o sent e o delivered de uma mesma tentativa carregam valores diferentes. Correlacione-os por verification_id, channel e address em ordem cronológica. Um reenvio no mesmo canal é o caso que invalida essa abordagem, já que seus eventos diferem apenas pelo timestamp.

verify.attempt.sent

Dispara assim que Bird entrega o código de verificação ao canal. Adiciona channel, address (o endereço único para o qual esta tentativa foi enviada, um número de telefone E.164 ou um endereço de e-mail), from (o endereço ou número de envio, null quando o canal não expõe remetente) e sent_at.
Exemplo de código
{
  "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

Dispara quando o canal confirma que o código de verificação chegou ao destinatário. Adiciona channel, address, carrier, mcc_mnc (a rede que processou e seu código de país/rede móvel) e delivered_at. Os campos carrier e mcc_mnc são sempre null para e-mail, WhatsApp e Telegram. Este evento omite from; leia-o de verify.attempt.sent para a mesma tentativa.
Exemplo de código
{
  "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

Dispara quando o canal não conseguiu entregar o código de verificação. Adiciona channel, address, reason (um enum aberto incluindo carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_restricted, channel_disabled, delivery_timeout e not_billable), error (detalhe apenas para exibição, ou null) e failed_at. Assim como verify.attempt.delivered, este evento omite from.
Exemplo de código
{
  "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" }
  }
}
Uma tentativa não entregue em um destinatário com mais de um canal disponível não encerra a verificação. Bird avança para o próximo canal no plano de entrega, que recebe seu próprio verify.attempt.sent. Um canal que falha antes de enviar emite verify.attempt.undelivered com reason: "channel_unavailable" e avança da mesma forma, assim como um que não entrega códigos de verificação para o país do destinatário, com reason: "channel_restricted" (veja Configuração de país). Essa tentativa não tem verify.attempt.sent nem relatório de entrega posterior. Bird emite verify.attempt.undelivered para cada tentativa com falha. Se o plano se esgota e as falhas registradas indicam que nenhum código foi enviado, também emite verify.verification.failed para a sessão.
Relatórios de entrega são indicativos, não garantidos. Operadoras e provedores de caixa de entrada variam no que confirmam e na velocidade. Em alguns mercados, eventos de tentativa chegam minutos depois ou não distinguem entrega de aceitação. Trate verify.verification.verified como o sinal definitivo de que o destinatário recebeu e usou seu código.

Webhooks

Registre um endpoint em qualquer tipo verify.* pela página Webhooks no dashboard ou pela API de webhooks. O Guia de webhooks cobre criação de endpoints, verificação da assinatura Standard Webhooks, tentativas de reenvio e reprocessamento de entregas com falha.

Próximos passos

PáginaO que cobre
Enviando verificaçõesAs chamadas de envio e verificação, status, configurações e limites
Webhooks e eventosConfiguração de endpoint, verificação de assinatura, tentativas de reenvio e reprocessamento
Referência API: criar uma verificaçãoSchema do endpoint de envio e detalhes de erro

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaVerify phone numbers at signupEntenda o conceitoWhat does OTP mean? One-time passwords explainedExplore a funcionalidadeCustomer verificationSiga o percurso de aprendizagemBuild your first integration
Experimente na prática e obtenha um resumo de implementação