---
title: "URL di callback SMS"
description: "Invia gli eventi di un messaggio SMS, o le risposte di un profilo di messaggistica, al tuo URL HTTPS. Tratta instradamento, verifica delle firme, nuovi tentativi e replay degli errori."
canonical: "https://bird.com/it-it/documentazione/guides/sms/callbacks"
---

# URL di callback SMS

Un URL di callback riceve gli eventi di un singolo messaggio SMS, o di tutti i messaggi di un profilo di messaggistica, al posto dei tuoi endpoint webhook. Usalo quando un messaggio o un programma ha bisogno di un proprio ricevitore.

Gestisci il segreto di firma, la cronologia dei tentativi e il replay nella dashboard, oppure tramite l'[API](/docs/api/reference/rotate-webhook-callback-signing-secret) e i comandi `bird webhooks callbacks`. Imposta l'URL di un profilo quando [crei un profilo di messaggistica](/docs/api/reference/create-sms-messaging-profile) o [lo aggiorni](/docs/api/reference/update-sms-messaging-profile).

## Scegli dove inviare gli eventi

L'URL viene determinato una sola volta, quando il messaggio viene accettato, e resta valido per tutta la durata del messaggio. Una modifica successiva al profilo non reinstrada un messaggio già in transito.

| Messaggio                                              | URL usato                                                                |
| ------------------------------------------------------ | ------------------------------------------------------------------------ |
| Inviato con `options.callback_url`                     | Quell'URL                                                                |
| Inviato con `options.callback_url` impostato su `null` | Nessuno: gli eventi vanno ai tuoi endpoint webhook                       |
| Inviato senza di esso, su un profilo di messaggistica  | Il `options.callback_url` del profilo                                    |
| Ricevuto su un numero di un profilo di messaggistica   | Il `inbound.callback_url` del profilo, poi il suo `options.callback_url` |
| Nessun URL tra i casi precedenti                       | Nessuno: gli eventi vanno ai tuoi endpoint webhook                       |

L'URL deve essere HTTPS, lungo al massimo 2048 caratteri e corrispondere a un indirizzo pubblico. Un host privato, di loopback o link-local restituisce `422`.

L'elenco dei tentativi di callback mostra dove è stato consegnato l'evento di un messaggio ricevuto.

## Cosa sostituisce l'URL

Finché un URL è in vigore, gli eventi di quel messaggio non passano dai tuoi endpoint webhook. Gli altri messaggi dello spazio di lavoro continuano a raggiungerli. Se un callback non riesce, gli eventi non vengono reindirizzati ai tuoi endpoint: per recuperarlo usa il [replay](#trovare-e-ripetere-i-callback-non-riusciti).

Le sottoscrizioni MCP Events e gli endpoint dei connettori continuano a ricevere gli eventi del messaggio.

Gli `callback_events` di un profilo di messaggistica scelgono quali eventi in uscita inviare all'URL, tra `sms.accepted`, `sms.sent`, `sms.delivered`, `sms.undelivered`, `sms.failed`, `sms.rejected` e `sms.expired`. Un evento escluso dall'elenco non raggiunge nemmeno alcun endpoint webhook per quel messaggio. Un profilo senza elenco e un invio senza profilo consegnano tutti gli eventi in uscita. `sms.received` non viene mai filtrato. I payload sono gli [eventi SMS](/docs/guides/sms/events).

## Verificare le firme

I callback usano gli stessi header [Standard Webhooks](/docs/guides/webhooks#verify-signatures) e la stessa firma HMAC-SHA256 degli endpoint webhook, quindi il codice di verifica che hai già funziona senza modifiche. La chiave è il segreto di firma dei callback del tuo spazio di lavoro, un unico segreto condiviso da tutti gli URL di callback e da tutte le richieste webhook delle sequenze vocali, quindi una rotazione vale per entrambi.

Il primo segreto non viene mai mostrato. Ruotalo per ottenerne uno utilizzabile, in **Webhooks → Direct callbacks** nella dashboard oppure con [Rotate callback signing secret](/docs/api/reference/rotate-webhook-callback-signing-secret). Il nuovo segreto compare una sola volta, quindi salvalo prima di lasciare la pagina. Per le 24 ore successive ogni callback viene firmato sia con il vecchio sia con il nuovo segreto, così puoi distribuire quello nuovo senza perdere consegne. Uno spazio di lavoro può avere al massimo 5 segreti validi contemporaneamente, quindi una nuova rotazione durante il periodo di sovrapposizione può essere rifiutata. Una rotazione diventa effettiva entro circa un minuto.

Ruota il segreto prima di affidarti alla verifica: finché non lo fai, i callback contengono una firma generata con un segreto che non puoi leggere.

## Nuovi tentativi e duplicati

I callback seguono la [pianificazione dei nuovi tentativi degli endpoint webhook](/docs/guides/webhooks#delivery-semantics): otto tentativi in circa 27,5 ore, e una risposta `2xx` entro 15 secondi conta come esito positivo. A differenza di un endpoint, un URL di callback non viene mai sospeso.

La consegna avviene almeno una volta e senza ordine garantito. Elimina i duplicati in base all'header `webhook-id` e ordina gli eventi in base a `timestamp` all'interno del payload.

## Trovare e ripetere i callback non riusciti

La scheda **Direct callbacks** in **Webhooks** nella dashboard e [List callback delivery attempts](/docs/api/reference/list-webhook-callback-attempts) mostrano i tentativi di callback dello spazio di lavoro, dal più recente, con l'URL, lo stato restituito dal tuo ricevitore e la latenza. I tentativi vengono conservati per tre giorni.

[Replay failed callback deliveries](/docs/api/reference/create-webhook-callback-replay) accoda un ulteriore tentativo per ogni evento i cui callback non sono riusciti in un intervallo di tempo che scegli tu, come fa il [replay delle consegne agli endpoint](/docs/guides/webhooks#replaying-failed-deliveries) per gli endpoint. Un evento consegnato con successo anche all'interno di quell'intervallo viene saltato. Un successo al di fuori dell'intervallo non conta, quindi quell'evento viene inviato di nuovo. Un singolo replay invia al massimo i 10.000 eventi non riusciti più vecchi dell'intervallo; dopo un'interruzione più lunga, esegui un altro replay con un orario di inizio successivo per i restanti.

Un replay invia all'URL registrato nei tentativi non riusciti, non ai tuoi endpoint webhook né all'URL attuale del profilo. Serve a recuperare un'interruzione del tuo ricevitore. Non può recuperare un messaggio inviato a un URL sbagliato: in quel caso invia di nuovo il messaggio. I replay rientrano nello stesso limite giornaliero dei replay degli endpoint.

## Passaggi successivi

- [Eventi SMS](/docs/guides/sms/events): il payload di ogni evento
- [Webhook ed eventi](/docs/guides/webhooks): firme, nuovi tentativi e replay in dettaglio
- [Inviare SMS](/docs/guides/sms/sending-sms): la richiesta di invio

## Related resources

- [Sending your first SMS](/learn/sms/sending-your-first-sms) (video)
- [What does SMS mean?](/explained/sms/what-does-sms-mean) (answer)
- [SMS](/sms-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms)
