---
title: "URLs de callback de SMS"
description: "Envie os eventos de uma mensagem de SMS, ou as respostas de um perfil de mensagens, para a sua própria URL HTTPS. Aborda roteamento, verificação de assinaturas, novas tentativas e reenvio de falhas."
canonical: "https://bird.com/pt-br/documentacao/guides/sms/callbacks"
---

# 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](/docs/api/reference/rotate-webhook-callback-signing-secret) e pelos comandos `bird webhooks callbacks`. Defina a URL de um perfil ao [criar um perfil de mensagens](/docs/api/reference/create-sms-messaging-profile) ou ao [atualizá-lo](/docs/api/reference/update-sms-messaging-profile).

## 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](#encontre-e-reenvie-callbacks-com-falha) 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](/docs/guides/sms/events).

## Verifique as assinaturas

Os callbacks usam os mesmos cabeçalhos [Standard Webhooks](/docs/guides/webhooks#verify-signatures) 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](/docs/api/reference/rotate-webhook-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](/docs/guides/webhooks#delivery-semantics): 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](/docs/api/reference/list-webhook-callback-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](/docs/api/reference/create-webhook-callback-replay) 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](/docs/guides/webhooks#replaying-failed-deliveries) 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](/docs/guides/sms/events): o payload de cada evento
- [Webhooks e eventos](/docs/guides/webhooks): assinaturas, novas tentativas e reenvio em detalhes
- [Envio de SMS](/docs/guides/sms/sending-sms): a solicitação de envio

## 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)
