URLs de callback de SMS
Uma URL de callback recebe os eventos de uma mensagem de SMS, ou de todas as mensagens de um perfil de mensagens, no lugar dos seus endpoints de webhook. Use-a quando uma mensagem ou um programa precisar de um receptor próprio.
Gerencie o segredo de assinatura, o histórico de tentativas e o reenvio no dashboard ou pela API e pelos comandos bird webhooks callbacks. Defina a URL de um perfil ao criar um perfil de mensagens ou ao atualizá-lo.
Escolha para onde vão os eventos
A URL é determinada uma única vez, quando a mensagem é aceita, e mantida durante toda a vida da mensagem. Uma alteração posterior no perfil não redireciona uma mensagem que já está em trânsito.
| Mensagem | URL usada |
|---|---|
Enviada com options.callback_url | Essa URL |
Enviada com options.callback_url definido como null | Nenhuma: os eventos vão para seus endpoints de webhook |
| Enviada sem ela, em um perfil de mensagens | O options.callback_url do perfil |
| Recebida em um número de um perfil de mensagens | O inbound.callback_url do perfil e, depois, o options.callback_url dele |
| Nenhuma URL vinda das opções acima | Nenhuma: os eventos vão para seus endpoints de webhook |
A URL deve ser HTTPS, ter no máximo 2.048 caracteres e usar um endereço público. Um host privado, de loopback ou link-local retorna 422.
A lista de tentativas de callback mostra para onde o evento de uma mensagem recebida foi entregue.
O que a URL substitui
Enquanto uma URL se aplica, os eventos dessa mensagem não passam pelos seus endpoints de webhook. As outras mensagens do espaço de trabalho continuam chegando a eles. Um callback com falha não é redirecionado para seus endpoints: use o reenvio para recuperá-lo.
As assinaturas de MCP Events e os endpoints de conectores continuam recebendo os eventos da mensagem.
Os callback_events de um perfil de mensagens escolhem quais eventos de saída vão para a URL, entre sms.accepted, sms.sent, sms.delivered, sms.undelivered, sms.failed, sms.rejected e sms.expired. Um evento que fica fora da lista também não chega a nenhum endpoint de webhook para essa mensagem. Um perfil sem lista e um envio sem perfil entregam todos os eventos de saída. sms.received nunca é filtrado. Os payloads são os eventos de SMS.
Verifique as assinaturas
Os callbacks usam os mesmos cabeçalhos Standard Webhooks e a mesma assinatura HMAC-SHA256 dos endpoints de webhook, então o código de verificação que você já tem funciona sem alterações. A chave é o segredo de assinatura de callbacks do seu espaço de trabalho, um único segredo compartilhado por todas as URLs de callback e por todas as solicitações de webhook de sequências de voz, então uma rotação afeta os dois.
O primeiro segredo nunca é exibido. Faça a rotação dele para obter um que você possa usar, em Webhooks → Direct callbacks no dashboard ou com Rotate callback signing secret. O novo segredo aparece uma única vez, então guarde-o antes de sair da página. Nas 24 horas seguintes, cada callback é assinado com o segredo antigo e com o novo, para que você implante o novo sem perder entregas. Um espaço de trabalho mantém no máximo 5 segredos válidos ao mesmo tempo, então uma nova rotação durante esse período pode ser recusada. Uma rotação entra em vigor em cerca de um minuto.
Faça a rotação antes de depender da verificação: até lá, os callbacks trazem uma assinatura feita com um segredo que você não consegue ler.
Novas tentativas e duplicatas
Os callbacks seguem o cronograma de novas tentativas dos endpoints de webhook: oito tentativas ao longo de cerca de 27,5 horas, e uma resposta 2xx em até 15 segundos conta como sucesso. Diferentemente de um endpoint, uma URL de callback nunca é pausada.
A entrega acontece pelo menos uma vez e sem ordem garantida. Elimine duplicatas pelo cabeçalho webhook-id e ordene pelo timestamp dentro do payload.
Encontre e reenvie callbacks com falha
A aba Direct callbacks em Webhooks no dashboard e o endpoint List callback delivery attempts mostram as tentativas de callback do espaço de trabalho, das mais recentes para as mais antigas, com a URL, o status que seu receptor retornou e a latência. As tentativas são guardadas por três dias.
Replay failed callback deliveries enfileira mais uma tentativa para cada evento cujos callbacks falharam em um intervalo de tempo que você escolhe, assim como o reenvio de entregas de endpoints faz para os endpoints. Um evento que também foi entregue com sucesso dentro desse intervalo é ignorado. Um sucesso fora do intervalo não conta, então esse evento é enviado de novo. Um reenvio envia no máximo os 10.000 eventos com falha mais antigos do intervalo; após uma interrupção mais longa, reenvie com um horário de início posterior para cobrir o restante.
Um reenvio vai para a URL registrada nas tentativas com falha, não para seus endpoints de webhook nem para a URL atual do perfil. Ele recupera uma interrupção no seu receptor. Ele não recupera uma mensagem enviada para uma URL errada; nesse caso, envie a mensagem de novo. Os reenvios contam para o mesmo limite diário dos reenvios de endpoints.
Próximos passos
- Eventos de SMS: o payload de cada evento
- Webhooks e eventos: assinaturas, novas tentativas e reenvio em detalhes
- Envio de SMS: a solicitação de envio
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.