Um webhook no Bitrix24 (Alaio) é 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.com/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.

Quem pode criar webhooks e dá para restringir isso?

Qualquer funcionário que consiga abrir a seção «Para desenvolvedores», não só os administradores. O módulo REST reserva aos administradores apenas alguns modelos prontos de integração, como os que adicionam um widget ao cartão do CRM. Um webhook de entrada ou de saída comum o funcionário cria sozinho, e ele funciona com as permissões desse funcionário. Não existe uma opção separada do tipo «webhooks só para administradores». Por isso, vale o administrador revisar a lista de webhooks de tempos em tempos (a próxima seção mostra onde ela fica). Bloquear a criação também não resolveria o risco principal: um webhook criado por um funcionário vê exatamente o que esse funcionário vê no CRM.

Onde ver os webhooks existentes e como excluir um?

Abra a seção «Para desenvolvedores» e vá até a lista de integrações. Cada funcionário vê apenas os próprios webhooks; o administrador vê todos e pode filtrar por autor. A chave (a parte secreta da URL) aparece só para o autor: se o administrador abrir o webhook de outra pessoa, verá asteriscos no lugar do código. Se uma integração está rodando e ninguém lembra quem a montou, procure por ela nessa lista pelo autor e pela data, não pela URL. Para excluir, use o menu da linha na lista. A partir daí o sistema externo passa a receber erros de autorização na hora, então descubra antes quem usa a chave. Confira à parte os webhooks de funcionários que já saíram da empresa; o que acontece com eles no desligamento está no guia de desligamento de funcionários.

Dá para criar um webhook somente leitura?

O webhook de entrada não tem uma caixa «somente leitura». As permissões são escolhidas por módulo na criação (CRM, tarefas, usuários e assim por diante), e dentro do módulo o webhook pode tanto ler quanto gravar. A única forma de limitar é pelos direitos do usuário em nome do qual ele roda: o webhook faz cada requisição em nome do autor e respeita a função dele. Isso leva a um caminho que funciona. Crie um usuário próprio para a integração, dê a ele uma função no CRM com acesso só de leitura às entidades necessárias e crie o webhook com esse usuário. Se a chave vazar, não dá para alterar nem excluir nada com ela. Lembre que esse usuário ocupa uma vaga no limite de usuários do seu plano. De bônus, a integração deixa de depender de um gerente específico: quando essa pessoa sai, a troca de dados continua funcionando.

O que entregar a um parceiro que vai nos enviar leads?

Normalmente o parceiro pede «uma URL ou um webhook», e as duas coisas são a mesma: o endereço de um webhook de entrada que o sistema dele vai chamar com crm.lead.add. Gere uma chave só com o módulo CRM, criada com o usuário de integração da seção anterior, e não com a sua própria conta de administrador. O endereço funciona como uma senha: quem tem acesso a ele pode gravar no seu CRM. Se a parceria acabar, exclua o webhook na lista de integrações e o acesso termina na hora. Se o parceiro só precisa enviar pedidos a partir de um site, um formulário do CRM é mais simples: aí nem é preciso chave da API REST.

O robô Webhook de saída: o que colocar no campo Handler?

O Bitrix24 tem um robô nativo chamado «Webhook de saída». Ele tem um único campo, Handler, onde você coloca o endereço do seu serviço: http ou https, com nome de domínio. O robô envia para lá uma requisição com o identificador do documento (document_id, por exemplo o negócio DEAL_10) e segue em frente na hora. Ele não espera resposta e não devolve nada ao processo. Também não envia os campos do negócio. Acrescente os valores necessários ao endereço como parâmetros: https://example.com/hook?deal={=Document:ID}&sum={=Document:OPPORTUNITY}. Mais um detalhe: se o REST não está disponível no seu plano, o robô simplesmente não faz nada, e nenhum erro aparece no log. Quando você precisa de um cabeçalho de autorização, de um corpo em JSON ou da resposta do serviço numa variável do processo, use o «Requisição HTTP». Quando o evento não pode se perder, use o «Webhook tolerante a falhas»: ele repete o envio conforme um intervalo, até dez tentativas.

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.