Um webhook no Bitrix24 é a forma de ligar o portal a um serviço externo sem escrever um aplicativo: o webhook de entrada dá ao sistema externo uma URL-chave para chamar a API REST do portal; o de saída faz o próprio Bitrix24 bater na sua URL quando ocorre um evento. É a maneira mais rápida de integração, mas tem limites sobre os quais a ajuda silencia. Vamos ver os dois tipos, a criação, as limitações e o terceiro cenário, que é o mais necessário com frequência: o webhook a partir de um processo de negócios.

Qual a diferença entre o webhook de entrada e o de saída?

O de entrada é uma URL do tipo https://portal.bitrix24.ru/rest/1/chave/, pela qual o serviço externo chama métodos da API REST: criar um lead, atualizar um negócio, obter a lista de tarefas. As permissões são definidas na criação (somente CRM, somente tarefas, etc.), e as ações são executadas em nome do funcionário dono da chave. O de saída é o oposto: você indica a URL do seu handler e o evento (lead criado, negócio atualizado), e o Bitrix24 envia um POST para lá a cada disparo. A combinação dos dois tipos dá uma integração bidirecional: o de saída avisa «surgiu um contato», o serviço externo enriquece os dados e, com o webhook de entrada, os grava de volta.

Onde criar um webhook e o que verificar?

Seção «Para desenvolvedores» (nos menus antigos — «Aplicativos») → «Outro» → «Webhook de entrada» / «Webhook de saída». Para o de entrada: escolha as permissões pelo mínimo necessário — uma chave com permissões «CRM + todo o resto», se vazar, entrega ao invasor toda a base; copie a URL com a chave e guarde-a como uma senha. Para o de saída: indique a URL do handler e o token do aplicativo para a verificação de autenticidade — o handler precisa conferir o token, caso contrário qualquer um que descubra o endereço poderá enviar eventos falsos. A disponibilidade dos webhooks depende do plano: em parte dos planos é necessária uma assinatura do Bitrix24 Market.

Quais são as limitações dos webhooks?

Três, nas quais as integrações se quebram. Limite de requisições: a API REST aceita cerca de duas requisições por segundo por portal, e ao ultrapassar — o erro QUERY_LIMIT_EXCEEDED; as operações em massa são empacotadas em chamadas batch. O webhook de saída não repete a entrega: se o seu handler ficou indisponível por três segundos, o evento se perde — o Bitrix24 não tenta de novo. E o webhook de saída carrega o mínimo de dados (o ID e o tipo do evento) — pelos campos você ainda precisa ir com o webhook de entrada à API REST. Por isso, «um barramento confiável baseado em webhooks de saída» é um mito: para eventos críticos é preciso entrega com confirmação e repetições.

Como enviar um webhook de um processo de negócios?

Um cenário frequente que não existe nas ações nativas: na transição do negócio para uma etapa, acionar um serviço externo — um sistema de gestão, um estoque, um bot de mensageiro. Isso é resolvido por dois robôs da Roboteka. O «Requisição HTTP» envia um GET ou POST com cabeçalhos e corpo, e retorna a resposta e o código de status para variáveis do processo — para cenários síncronos «perguntei e recebi a resposta» (a resposta é analisada pelo robô «Extrair valor do JSON por caminho»). O «Webhook tolerante a falhas» — para o cenário «entregar obrigatoriamente»: ele repete o envio quando o receptor está indisponível, e o evento não se perde enquanto o serviço externo reinicia. Regra de escolha: precisa da resposta aqui e agora — requisição HTTP; precisa da garantia de entrega da notificação — webhook tolerante a falhas.

O webhook não funciona: checklist

O de entrada retorna erro: verifique as permissões da chave (o método exige um escopo que não existe), se o funcionário dono está ativo (funcionário demitido = chave morta) e o limite de requisições. O de saída não chega: verifique se o handler responde com código 200 rapidamente (uma resposta lenta o Bitrix24 considera erro), se a URL é acessível de fora (não localhost, não bloqueada por firewall) e se o evento é mesmo aquele — «atualização de negócio» não dispara na mudança de etapa do kanban de tarefas. E lembre-se da ausência de repetições: se o receptor estava fora do ar, o evento precisa ser recuperado manualmente — ou enviado, desde o início, pelo webhook tolerante a falhas a partir do processo.

Conclusão

Os webhooks são a forma mais barata de integração com o Bitrix24: o de entrada para gerenciar o portal de fora, o de saída para sinais para fora e, a partir dos processos de negócios — robôs com requisição HTTP e garantia de entrega do catálogo da Roboteka. Não há o cenário que você precisa? Descreva a tarefa, criamos o robô de graça.