Verificar a entrega de webhooks
Confira qual endpoint deve receber o evento
Abra Settings → Integrations → Webhooks. Confirme que o endpoint está habilitado e inscrito no evento necessário. A permissão de webhooks da conta abrange endpoints, segredos e registros de entrega de toda a conta; a permissão de CRM sozinha não concede esse acesso.
Para SMS, confira os identificadores de remetente selecionados. All Sender IDs inclui todos os eventos SMS assinados da conta; uma lista selecionada é comparada ao remetente original da mensagem. Os demais tipos de evento não são afetados.
Alterar um filtro não reenvia o histórico
A seleção de remetentes é verificada a cada tentativa, inclusive nas novas tentativas. Alterações não reenviam eventos antigos nem redirecionam entregas já enfileiradas.
Abrir documentação de webhooks
Leia a tentativa de entrega
O registro mostra horário, status, evento, endpoint, resposta HTTP e erro. Identifique o evento e endpoint da tentativa investigada e compare com os registros do receptor.
Nenhuma tentativa correspondente
Confira as inscrições em eventos, o estado do endpoint e os filtros de remetente SMS antes de investigar o código receptor.
Tentativa com falha
Use a resposta HTTP ou o erro de rede para identificar a camada receptora que rejeitou ou não recebeu a solicitação.
Confirmação bem-sucedida
Verifique separadamente o processamento da aplicação. Uma confirmação HTTP não prova que todas as ações seguintes foram concluídas.
Se o firewall restringe solicitações recebidas, use a lista atual de IPs de entrega nas configurações da conta. Verifique assinaturas mesmo com uma lista de IPs permitidos.
Confira primeiro a verificação da assinatura
O IllyVoIP envia solicitações POST JSON com o cabeçalho Illyvoip-Signature. Valide-o com o segredo do webhook e o corpo bruto original antes de processar o evento.
A entrada assinada é o timestamp, um ponto e o corpo bruto. Interpretar e recodificar o JSON antes da verificação pode alterar essa entrada. Consulte a referência atual para o procedimento exato de HMAC SHA-256.
O segredo de assinatura do webhook é separado da chave API do cliente. Se ele foi rotacionado, atualize o receptor conforme seu procedimento habitual de troca de credenciais. Não exponha nenhum segredo nos registros de suporte.
Entenda a resposta HTTP
Qualquer 2xx
Confirma a entrega. Uma resposta 200 vazia basta.
Falha de rede, sem resposta, 408, 429 ou 5xx
Pode ser reenviado conforme a política documentada de novas tentativas.
3xx ou outros 4xx
Interrompe a entrega. Verifique redirecionamentos, regras de acesso e validação do receptor em vez de esperar uma nova tentativa automática.
Confirme rapidamente os eventos válidos e coloque tarefas demoradas em uma fila separada. O receptor deve lidar com recebimentos repetidos do mesmo evento de forma segura.
Evite processamento duplicado com o ID do evento
Salve o campo id do corpo como chave estável de deduplicação. O cabeçalho Illyvoip-Delivery identifica a tarefa de entrega; não substitui o ID do evento.
Para correlacionar SMS, siga a documentação atual de respostas de envio e webhooks. Identificadores de tarefa de entrega e de mensagem têm funções diferentes.
Se precisar de ajuda, informe ID do evento, horário e fuso da tentativa, código de resposta e erro do receptor sem dados sensíveis. Mantenha segredos, chaves API e conteúdos de outros eventos privados.
Crie, edite e desative um endpoint
Em Integrations → Webhooks, escolha Add webhook, informe a URL HTTPS receptora e selecione apenas os eventos necessários. Confira filtros de remetente SMS quando aplicáveis e salve. Guarde com segurança o segredo exibido; ele não é a chave API da conta.
Use Edit no endpoint correto para alterar nome, eventos, filtros ou estado habilitado. A URL é somente leitura: crie outro endpoint para uma URL diferente, atualize seu segredo no receptor e retire o antigo quando estiver pronto. Confira a linha salva antes do teste. Endpoints duplicados podem enviar notificações separadas ao mesmo receptor. Antes de remover um endpoint antigo, confira qual aplicação o usa; removê-lo não desfaz eventos já processados.
Coordene mudanças de segredo
Rotacione o segredo somente quando puder atualizar a aplicação receptora. Leia a confirmação, guarde o novo segredo com segurança e atualize o receptor antes de depender de novas entregas. Não suponha que o segredo antigo funcionará indefinidamente nem que a rotação reenviará eventos históricos. O registro cobre diagnóstico recente, não um arquivo completo; mantenha seus próprios registros seguros de eventos e processamento.