Visão geral

Webhooks permitem que a FonteData avise sua aplicação em tempo real quando um evento acontece, em vez de você precisar consultar a API repetidamente para saber se algo novo chegou.

Quando usar

O caso de uso principal hoje é SMS bidirecional: quando alguém responde a um SMS enviado pela sua conta — seja uma resposta comum, seja um SAIR para não receber mais —, você é notificado no exato momento em que a resposta chega.

O webhook é o único caminho para receber essas respostas: não há consulta de polling equivalente na API. Se você quer tratar respostas dos seus destinatários, registre um webhook antes de começar a enviar — veja Reentrega e confiabilidade para o que acontece quando a entrega falha.

A infraestrutura de webhooks é genérica: hoje os únicos tipos de evento disponíveis são os de SMS (veja o catálogo de eventos), mas novos tipos serão adicionados ao longo do tempo sem mudar a forma como você registra ou recebe.

Como registrar

Os webhooks são configurados pelo painel, não pela API:

1. Acesse app.fontedata.com e faça login na sua conta.
2. Navegue até a seção Webhooks do dashboard.
3. Cadastre a URL que vai receber os eventos (precisa ser https:// e publicamente acessível — não são aceitos endereços de rede privada ou localhost) e selecione os tipos de evento que deseja receber.
4. Ao salvar, um segredo de assinatura (signing secret) é exibido — copie e guarde nesse momento, pois ele não é mostrado novamente (veja Assinatura e verificação).

Você pode ter mais de um webhook cadastrado, editar a URL e os tipos de evento, ou desativar/remover um webhook a qualquer momento, tudo pelo painel.

Como o evento é entregue

Cada evento é entregue como uma requisição POST para a URL cadastrada, com corpo em JSON e o cabeçalho de assinatura (X-FonteData-Signature). O formato do corpo — o envelope do evento — é o mesmo para todos os tipos de evento; veja o detalhamento em Catálogo de eventos.

O que sua aplicação precisa fazer

• Responder com um status 2xx (por exemplo, 200 OK) em até 10 segundos a partir do recebimento da requisição. Redirecionamentos não são seguidos: um 3xx conta como falha, então cadastre já a URL final.
• Fazer isso rapidamente: se o processamento do evento demandar tempo (gravar em banco, chamar outros sistemas), responda 2xx primeiro e processe de forma assíncrona depois — veja a recomendação em Reentrega e confiabilidade.
• Verificar a assinatura de cada requisição antes de confiar no conteúdo — veja Assinatura e verificação.

Se sua aplicação não responder 2xx dentro do prazo (timeout, erro 5xx, indisponibilidade), o evento entra na fila de reentrega — veja Reentrega e confiabilidade para os detalhes de backoff e janela de tentativas.