Um webhook que «não funciona» são, no Bitrix24 (Alaio), duas falhas bem diferentes sob a mesma palavra, e a correção de uma não serve para a outra: ou um evento de saída nunca chega ao seu handler, ou uma chamada de entrada devolve erro em vez de dados. Uma sincronização morta, um bot que parou de escrever, um sistema contábil sem os negócios de ontem: cada sintoma é um desses dois casos disfarçado. Primeiro descubra qual é o seu e depois percorra as verificações na ordem.

Saída ou entrada: qual metade quebrou?

Um webhook de entrada é uma URL com uma chave pela qual o seu serviço chama o portal; o de saída é o contrário — o portal chama você quando um evento acontece. Se os seus logs mostram uma requisição saindo e uma mensagem de erro voltando, o problema é de entrada e o próprio erro nomeia a causa. Se não mostram nada, o problema é de saída — e não existe erro em lugar nenhum, o que é justamente o que torna o diagnóstico lento. Como se criam os dois tipos está no guia de webhooks; esta página é sobre o que fazer quando eles ficam mudos.

Por que o webhook de saída nunca chega ao meu handler?

Os eventos não viajam do portal direto para a sua URL. Eles entram numa fila em um servidor de entrega separado, e é ele que envia o POST. Três propriedades desse servidor explicam a maior parte do silêncio. O handler precisa estar acessível pela internet pública: um endereço em localhost ou dentro de uma rede privada não recebe nada, e um firewall que só admite parceiros conhecidos tem o mesmo efeito. Ele precisa responder rápido: a fila observa o tempo de resposta e chama handlers lentos com menos frequência, esticando o intervalo entre as tentativas — um handler pesado vira um handler não confiável sem nunca falhar de forma visível. E a carga é propositalmente enxuta, basicamente o identificador da entidade e o nome do evento, então um código que espera valores completos de campos lê uma estrutura vazia. Busque os campos com uma chamada REST separada.

É mesmo o evento que você assinou?

A segunda causa mais comum é uma assinatura saudável do evento errado. Eventos de atualização disparam a cada mudança da entidade, inclusive as que a sua própria automação faz — isso aparece como entregas duplicadas e às vezes vira um laço. Handlers registrados na seção de recursos para desenvolvedores e handlers registrados por um aplicativo via event.bind ficam em listas diferentes: a assinatura que você está olhando pode não ser a que roda — e os vínculos de um aplicativo somem quando ele é removido ou atualizado. A verificação custa um minuto: dispare a ação na mão e veja no log de acesso se chega um POST.

Meu handler estava fora do ar: dá para recuperar o evento?

Não, e essa é a propriedade que a maioria dos projetos de integração ignora. Se o seu servidor não responder ou devolver erro, o servidor de fila registra a falha e não reenvia o evento. Não há novas tentativas nem fila de mensagens mortas: dez segundos de deploy custam, em silêncio, todos os eventos daquela janela.

Existem duas saídas. Para o sentido de entrada, vincule a assinatura como evento offline: o portal guarda os eventos numa fila que o seu serviço consome no próprio ritmo com event.offline.get, de modo que a indisponibilidade atrasa a entrega em vez de destruí-la. Para chamadas que começam dentro do portal, envie-as a partir de um fluxo de trabalho: Webhook tolerante a falhas repete as tentativas fracassadas no intervalo que você definir, permite declarar quais códigos de status contam como sucesso, informa quantas tentativas foram feitas e avisa os funcionários escolhidos se a entrega não acontecer.

Por que o webhook de entrada devolve erro?

Aqui você tem um código — leia ele, não a frase ao lado. Um erro de permissão significa que a chave foi criada sem o escopo que o método exige, e escopos são fixados na criação: a chave precisa ser reemitida. Um erro de acesso costuma significar que a chave está certa, mas o dono dela não: o webhook age com os direitos do funcionário que o criou, então um dono desativado, ou um que não enxerga o funil, falha com um token perfeitamente válido. QUERY_LIMIT_EXCEEDED é o limitador de frequência, não uma chave quebrada: operações em massa vão empacotadas em chamadas batch e repetidas com atraso crescente. Uma chamada em HTTP simples, sem HTTPS, é rejeitada de cara.

Como testar um webhook em vez de adivinhar?

Registre o corpo cru da requisição antes de interpretá-lo: metade dos casos de «o webhook quebrou» é um handler que recebeu o POST e caiu no próprio parsing. Verifique também o remetente — junto com as chamadas de evento vem um token de aplicativo, e compará-lo com o valor guardado é ao mesmo tempo a checagem de segurança e a resposta rápida para saber se aquele POST veio mesmo do portal.

O sentido contrário se testa de dentro do portal: coloque Requisição HTTP GET/POST num fluxo — ela envia uma requisição ao seu endpoint e devolve o corpo da resposta, o código de status e uma marca Y/N, ou seja, mostra se o seu endpoint responde à rede do portal; Extrair valor do JSON pelo caminho tira um campo para uma linha de log legível. Se o fluxo que deveria enviar a requisição nem chegou a iniciar, a trilha passa para as regras de automação que não rodam.

O que vem depois

Silêncio quer dizer saída; uma mensagem de erro, entrada: só essa divisão economiza a maior parte do tempo. Depois, projete a favor da restrição e não contra ela — eventos nunca são reenviados, então tudo que não pode se perder entra por uma assinatura offline e sai pelo webhook tolerante a falhas, ambos blocos comuns das regras de automação no Bitrix24. Os demais estão no catálogo da Roboteka; se faltar o que você precisa, descreva a tarefa: construímos de graça e colocamos na biblioteca comum.