Sign inGet Started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Eventi di Verify

Una verifica produce eventi per la propria sessione e per ogni tentativo di consegna. La sessione inizia quando Bird crea la verifica e converte quando il destinatario inserisce il codice corretto. Ogni invio di codice di verifica crea un tentativo su un canale, che può risultare consegnato o non consegnato. I reinvii e il failover di canale aggiungono tentativi alla stessa sessione.
EventoAsseSi attiva quando
verify.verification.createdSessioneUna verifica viene creata e il primo codice di verifica è accodato per l'invio
verify.attempt.sentConsegnaUn codice di verifica è stato consegnato a un canale per il recapito
verify.attempt.deliveredConsegnaIl canale ha confermato che il codice di verifica ha raggiunto il destinatario
verify.attempt.undeliveredConsegnaIl canale non è riuscito a recapitare il codice di verifica al destinatario
verify.verification.verifiedSessioneIl destinatario ha inviato il codice corretto prima della scadenza della verifica
verify.verification.failedSessioneIl piano di recapito si è concluso con errori che indicano che nessun codice di verifica è stato inviato
Una verifica che non converte non emette mai verify.verification.verified, e il suo stato da solo non indica il motivo. failed è condiviso: una verifica finisce in quello stato sia quando sono stati inviati troppi codici di verifica errati, con reason attempts_exhausted, sia quando il piano di recapito si conclude con errori che indicano che nessun codice è stato inviato, con reason undeliverable. Solo il secondo caso emette verify.verification.failed, e quell'evento porta sempre reason undeliverable, quindi è l'evento a distinguere i due casi dove lo stato non può farlo. Una finestra di validità che scade si risolve in expired. Né expired né un failed per tentativi esauriti emette un evento proprio. Un canale di fallback crea il proprio verify.attempt.sent, quindi una singola verifica può avere più sequenze di tentativi.
L'elenco dei tipi di evento è aperto: nuovi tipi possono essere aggiunti nel tempo, quindi tratta un valore non riconosciuto come un evento futuro anziché come un errore.

L'envelope dell'evento

Gli eventi arrivano al tuo endpoint webhook nell'envelope annidato Standard Webhooks descritto nella Guida ai webhook: un type, un timestamp e un oggetto data specifico per tipo. L'identità dell'evento non è nel body: si trova nell'header webhook-id HTTP, che è stabile tra i retry della stessa consegna ed è la tua chiave di deduplicazione.
Il data di ogni evento contiene questa base identificativa:
  • verification_id: la verifica a cui appartiene questo evento, corrispondente al id di POST /v1/verify/verifications
  • workspace_id: lo spazio di lavoro che ha creato la verifica
  • to: l'identità del destinatario della verifica, un oggetto con email e/o phone_number corrispondente a quanto fornito nella richiesta di creazione. Un singolo tentativo di codice di verifica riporta l'unico indirizzo a cui è stato inviato nel proprio campo address
  • metadata: l'oggetto a formato libero dalla richiesta di creazione, restituito invariato, oppure null quando la richiesta non ne conteneva

Eventi di sessione

verify.verification.created

Si attiva non appena viene creata una verifica e il primo codice di verifica è messo in coda. Aggiunge channel (il canale su cui esce il primo tentativo), status: "pending" e created_at.
Esempio di codice
{
  "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

Si attiva quando POST /v1/verify/verifications/check conferma il codice corretto. Aggiunge status: "verified", channel (il canale che ha consegnato il codice inviato, oppure null quando la verifica si è risolta senza attribuire un canale) e verified_at.
Esempio di codice
{
  "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

Si attiva quando il piano di recapito è esaurito e gli errori registrati indicano che nessun codice di verifica è stato inviato. Il payload aggiunge status: "failed", reason: "undeliverable", channel (l'ultimo canale provato, o null quando nessuno è stato attribuito), last_attempt_reason e failed_at.
channel_unavailable, channel_disabled, channel_restricted e not_billable indicano che un tentativo non ha inviato un codice di verifica. Se un tentativo potrebbe averlo inviato, un bounce successivo, un rifiuto dell'operatore o un timeout di recapito lascia la sessione in sospeso e non emette verify.verification.failed. Un codice precedente può ancora completare la verifica prima della scadenza.
last_attempt_reason usa gli stessi motivi di errore di verify.attempt.undelivered. Un errore not_billable significa che l'invio non è stato addebitato: controlla il saldo dello spazio di lavoro e se i prezzi sono disponibili per la destinazione.

Eventi di recapito

Ogni codice di verifica inviato da Bird è un tentativo. Un reinvio o un failover di canale crea un altro tentativo sulla stessa verification_id, con la propria sequenza di recapito. Nessun evento contiene un identificatore di tentativo e webhook-id non li raggruppa: identifica un singolo recapito di un singolo evento, quindi sent e delivered per uno stesso tentativo hanno valori diversi. Abbinali in base a verification_id, channel e address in ordine temporale. Un reinvio sullo stesso canale è il caso che vanifica questo approccio, perché i suoi eventi differiscono solo per timestamp.

verify.attempt.sent

Si attiva quando Bird ha consegnato il codice di verifica al canale. Aggiunge channel, address (l'indirizzo singolo a cui è stato inviato il tentativo, un numero di telefono E.164 o un indirizzo email), from (l'indirizzo o il numero del mittente, null quando il canale non espone un mittente) e sent_at.
Esempio di codice
{
  "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

Si attiva quando il canale conferma che il codice di verifica ha raggiunto il destinatario. Aggiunge channel, address, carrier, mcc_mnc (la rete di gestione e il relativo codice paese/rete mobile) e delivered_at. I campi carrier e mcc_mnc sono sempre null per email, WhatsApp e Telegram. Questo evento omette from; leggilo da verify.attempt.sent per lo stesso tentativo.
Esempio di codice
{
  "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

Si attiva quando il canale non è riuscito a recapitare il codice di verifica. Aggiunge channel, address, reason (un'enum aperta che include carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_restricted, channel_disabled, delivery_timeout e not_billable), error (dettaglio a solo scopo visivo, o null) e failed_at. Come verify.attempt.delivered, questo evento omette from.
Esempio di codice
{
  "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" }
  }
}
Un tentativo non recapitato su un destinatario con più di un canale disponibile non termina la verifica. Bird avanza al canale successivo nel piano di recapito, che ottiene il proprio verify.attempt.sent. Un canale che fallisce prima dell'invio emette verify.attempt.undelivered con reason: "channel_unavailable" e avanza allo stesso modo, così come uno che non trasporta codici di verifica verso il paese del destinatario, con reason: "channel_restricted" (vedi Configurazione paese). Quel tentativo non ha verify.attempt.sent né report di recapito successivi. Bird emette verify.attempt.undelivered per ogni tentativo fallito. Se il piano è esaurito e gli errori registrati indicano che nessun codice di verifica è stato inviato, emette anche verify.verification.failed per la sessione.
I report di recapito sono indicativi, non garantiti. Operatori e provider di posta variano in ciò che confermano e in quanto tempo lo fanno. In alcuni mercati gli eventi dei tentativi arrivano minuti dopo o non distinguono il recapito dall'accettazione. Considera verify.verification.verified come il segnale definitivo che il destinatario ha ricevuto e usato il proprio codice.

Webhook

Registra un endpoint per qualsiasi tipo verify.* dalla pagina Webhooks nella dashboard o tramite le API dei webhook. La Guida ai webhook tratta la creazione degli endpoint, la verifica della firma Standard Webhooks, i retry e il replay delle consegne fallite.

Passi successivi

PaginaCosa tratta
Invio delle verificheLe chiamate di invio e controllo, stati, impostazioni e limiti
Webhook ed eventiConfigurazione degli endpoint, verifica della firma, retry e replay
Riferimento API: creare una verificaSchema dell'endpoint di invio e dettagli degli errori

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaVerify phone numbers at signupComprendi il concettoWhat does OTP mean? One-time passwords explainedEsplora la funzionalitàCustomer verificationSegui il percorso di apprendimentoBuild your first integration
Prova l'esercitazione e ottieni un brief di implementazione