API ou webhook no Bitrix24: a pergunta está mal colocada
Webhook e API não são alternativas. No Bitrix24, o webhook de entrada é uma das duas formas de autorizar uma chamada da própria API REST, e a outra é o token de OAuth 2.0 dos aplicativos (documentação de autorização). A decisão real fica entre webhook e aplicativo.
| Se a pergunta é | A resposta prática |
|---|---|
| “uso webhook ou API?” | O webhook usa a API. A escolha é de mecanismo de autorização, não de tecnologia |
| “uso webhook ou aplicativo?” | Depende de onde a integração roda, de quais métodos ela chama e de quem responde por ela |
O desenho da URL, os escopos e os códigos de erro estão em a primeira chamada à API REST do Bitrix24, e o requisito de plano de cada rota, nos caminhos oficiais de integração do Bitrix24. Aqui o assunto é qual webhook usar, o que ele não resolve e o que acontece quando um evento se perde.
Webhook de entrada e webhook de saída: o que cada um faz
A documentação oficial de webhooks organiza a escolha em três colunas, reproduzidas abaixo em português com as frases originais.
| Webhook de entrada | Webhook de saída | |
|---|---|---|
| O que faz | “Calls REST API methods through a secret URL” | “Sends a Bitrix24 event to your handler URL” |
| Quando serve | “Quick integrations, tests, scripts, and data exchange with an external system” | “Reacting to data changes, starting synchronization, and notifying an external system” |
| O que considerar | “Works within the scope and employee permissions. Some methods require the application context and are not available through a webhook” | “The handler must be available from the external network. To retrieve full object data, an additional method call is usually required” |
A confusão mais comum está na direção. O webhook de entrada chama o Bitrix24; o de saída é chamado pelo Bitrix24. E o de saída não executa nada por conta própria: “An outbound webhook does not call a method by itself. It passes an event to your handler, and the handler decides whether an additional REST API request is required.”
A nota oficial em pt-BR publicada em 18 de junho de 2024 define webhook só pelo lado do envio: “Um webhook é uma maneira de um aplicativo fornecer informações em tempo real para outros aplicativos.” A definição cobre o de saída e deixa de fora o de entrada, que é o mais usado na integração com o Bitrix24.
Quando o webhook de entrada é a escolha certa
A documentação lista quatro sinais para escolher o webhook de entrada: quando é preciso testar rapidamente a chamada de um método no navegador, no construtor de requisições ou com curl; quando a integração trabalha com uma única conta Bitrix24; quando as requisições devem ser executadas em nome de um colaborador específico; e quando não são necessários interface de aplicativo, handler de eventos nem instalação da solução em outras contas.
O terceiro sinal tem consequência operacional: como a requisição corre em nome de quem criou o webhook, as permissões desse colaborador definem o alcance da integração, e um desligamento muda o resultado das chamadas. O passo a passo de criação do webhook de entrada, com os caminhos de menu em português e em inglês, está no guia da primeira chamada.
Quando o webhook de saída é a escolha certa
Os três sinais oficiais: quando um sistema externo precisa saber automaticamente das mudanças no Bitrix24; quando a sincronização deve começar depois que um objeto é criado ou alterado; e quando basta receber o evento e o identificador do objeto, com os dados detalhados buscados depois por um método próprio.
O handler recebe os dados como parâmetros de requisição HTTP no formato application/x-www-form-urlencoded. São quatro campos:
| Campo | Tipo | Conteúdo |
|---|---|---|
event |
string | “Name of the event that triggered the outbound webhook” |
data |
object | dados do evento; em eventos de CRM, o identificador costuma vir em data[FIELDS][ID] |
ts |
integer | “Event sending time in Unix timestamp format” |
auth |
object | dados de autorização de serviço, com domain, member_id e application_token |
O fluxo típico descrito pela documentação é este: o handler pega o identificador do negócio em data[FIELDS][ID] e chama crm.item.get com entityTypeId = 2 para obter os dados completos. Ou seja, o evento avisa; quem busca o conteúdo é a sua aplicação.
Quando o webhook não basta e a integração precisa de aplicativo
Três condições, segundo a mesma página, tiram o webhook da mesa: a integração precisa ser instalada em contas diferentes do Bitrix24; a solução precisa de interface dentro do Bitrix24; ou a integração usa métodos que só funcionam no contexto de aplicativo.
O terceiro caso aparece em produção como um erro específico. A página de escopos e permissões explica: “Some methods work only in the application context. When a webhook calls such a method, Bitrix24 returns the WRONG_AUTH_TYPE error with the Application context required description. The placement.bind method behaves this way, for example.” A documentação de webhooks cita ainda métodos de incorporação de widgets, alguns métodos de telefonia e cenários de chatbot.
Quando o erro é esse, ampliar o escopo não resolve. A recomendação oficial para aplicativo local ou OAuth 2.0 nesses casos já está registrada no guia do pilar.
Segurança da URL: o que a chave secreta dá de acesso
O helpdesk em português, atualizado em 25 de julho de 2025, é direto sobre o risco: “Não compartilhe sua chave secreta do webhook com ninguém e evite usá-la em qualquer código ou script de página da web. Se pessoas não autorizadas virem esta chave, elas poderão obter acesso aos dados do seu Bitrix24.”
Três comportamentos completam o quadro e costumam aparecer só depois que algo quebra.
- A chave troca de dono. “A chave está disponível apenas para o criador do webhook. Quando um administrador edita um webhook de outro usuário, a chave secreta é redefinida e esse administrador se torna o proprietário desse webhook.” Uma edição de rotina derruba a integração e muda as permissões que valem para ela.
- O webhook expira. A documentação registra que o mecanismo “supports an expiration date” e que, passada a data, “the request stops working and returns an authorization error”.
- O teste por GET deixa rastro. A URL “can be retained in browser history, logs, and monitoring services”, e a orientação oficial é usar POST em integrações de produção.
No webhook de saída, a verificação vem do lado do seu servidor: “Compare the auth[application_token] value in the request with the token value shown in the outbound webhook settings. If the values do not match, the request cannot be considered trusted.” Sem essa comparação, qualquer requisição para a URL do handler é tratada como legítima.
As páginas oficiais também divergem sobre quem pode criar webhooks na conta. As duas versões, com as fontes e a data, estão em quem pode criar webhooks, segundo as páginas oficiais.
Erro e reprocessamento: o que a Bitrix24 garante e o que não garante
Esta é a parte que muda o desenho de uma integração séria, e ela sai do cruzamento de duas páginas oficiais.
O ponto de partida está na documentação de eventos: “No retries. If your server does not respond or returns an error, the Bitrix24 queue server will log the failure but will not resend the event.” Se o seu servidor estava fora do ar por dez minutos, os eventos daqueles dez minutos não voltam.
A saída indicada pela própria página são os Offline Events: “If it is important to process all events without loss, use Offline Events. They allow you to retrieve events from the queue manually.” A fila existe e é lida sob demanda.
Acontece que essa saída não está disponível para o webhook de saída. A mesma página registra, na linha do webhook de saída, “Only online events available in the webhook list”, e acrescenta que “the event.bind method works only in the context of application authorization” e que “only an administrator can work with the offline event queue”, restrição que vale para event.offline.get, event.offline.list, event.offline.clear e event.offline.error.
A conclusão prática: quem precisa de garantia de processamento não resolve com webhook de saída. O caminho é um aplicativo assinando eventos offline ou uma rotina de conferência que compare o que existe no Bitrix24 com o que existe no sistema de destino.
Some a isso a carga: “Load cannot be regulated. When mass data changes occur, you will receive many consecutive calls. If a thousand deals are changed simultaneously in Bitrix24, the handler will receive a thousand calls.” Uma edição em massa vira uma rajada no seu servidor, efeito que entra nos riscos de desenho de integração com ERP.
Limitações do webhook de saída
A documentação lista restrições que decidem viabilidade antes de qualquer linha de código.
- Na versão on-premise, o webhook de saída exige licença ativa.
- Webhooks de saída não estão disponíveis em modos de demonstração.
- A URL do handler precisa ser pública, alcançável pela rede externa e aceitar POST.
- Endereços de localhost, de rede local e handlers com certificado SSL autoassinado não servem.
Em ambiente corporativo, os dois últimos itens costumam ser o gargalo real: o handler existe, mas está atrás de uma rede fechada.
Onde ver os webhooks criados e a carga de cada um
Na guia Integrações, segundo o helpdesk, aparecem “nome dos webhooks e aplicativos, quais eventos eles acionam, a quais ferramentas eles têm acesso, qual usuário os criou”. A visibilidade depende do papel: “os administradores do Bitrix24 podem acessar todos os webhooks e aplicativos criados. Um usuário comum só pode acessar aqueles que ele criou.”
A guia Estatísticas mostra o volume de requisições, com uma janela curta: “O período máximo para visualização das estatísticas é de 14 dias.” É pouco para investigação retroativa, então o histórico de carga precisa ser guardado do seu lado.
Checklist antes de ligar o webhook em produção
- O método está disponível para o escopo selecionado.
- O colaborador que criou o webhook tem permissão sobre o objeto que a integração manipula.
- A conta tem acesso à API REST.
- As requisições saem por HTTPS.
- A data de expiração do webhook está anotada com um responsável.
- No webhook de saída, o handler compara o
application_tokenantes de processar a requisição. - Existe um plano para o evento perdido, por rotina de conferência ou por aplicativo com eventos offline.
- Alguém sabe onde ver a carga, lembrando que a janela de estatísticas é de 14 dias.
Perguntas frequentes
Qual a diferença entre webhook e API?
No Bitrix24 não é uma oposição. A API REST é o conjunto de métodos, e o webhook de entrada é uma das duas formas de autorizar a chamada desses métodos, ao lado do token de OAuth 2.0 dos aplicativos. O webhook de saída é o caminho inverso: o Bitrix24 avisa o seu servidor quando um evento acontece.
Para que serve um webhook?
No Bitrix24, o de entrada serve para integrações rápidas, testes, scripts e troca de dados com sistemas externos, executando métodos em nome de quem o criou. O de saída serve para reagir a mudanças, iniciar sincronizações e notificar outro sistema, entregando o evento e o identificador do objeto ao seu handler.
O Bitrix24 tem API?
Tem. O Bitrix24 expõe uma API REST com métodos de CRM, tarefas, calendário, telefonia e outros módulos, chamada por webhook de entrada ou por aplicativo com OAuth 2.0. O passo a passo da primeira chamada, com escopos, limites e códigos de erro, está no guia da API REST do Bitrix24.
O webhook do Bitrix24 é gratuito?
O webhook em si não é cobrado à parte, mas depende do plano da conta. O helpdesk oficial registra que “a capacidade de criar webhooks e aplicativos está disponível apenas em alguns planos”. O requisito de plano de cada rota está no guia do pilar de integrações.
Próximo passo
Definido o tipo de webhook, a decisão seguinte é de operação: quem cria, quem revisa a expiração e como a empresa descobre que um evento se perdeu.
A Tiqtech é parceira Bitrix24 e desenha essas integrações com a equipe interna: conheça a implantação e integração com a Tiqtech ou falar com a Tiqtech sobre o seu webhook.