Amplie as Possibilidades do Bitrix24 com Webhooks

Webhooks no Bitrix24: Expanda o Poder da sua Plataforma

O Bitrix24 é uma plataforma robusta, repleta de ferramentas essenciais para a gestão de negócios: CRM, tarefas e projetos, armazenamento em nuvem, calendário corporativo, automação de processos, criador de sites, marketing automatizado — e muito mais.

Mas… e quando essas ferramentas ainda não forem o suficiente?
É aí que entram os webhooks, abrindo as portas para funcionalidades praticamente ilimitadas.

Afinal, o que é Webhook?!

Se você já ouviu um consultor dizer “O Bitrix não tem essa função, mas podemos criar um webhook”, saiba que ele estava se referindo a uma solução poderosa e flexível.

Com webhooks, você pode:

1. Adicionar, modificar, excluir, importar ou duplicar leads, tarefas, pedidos, empresas, contatos, faturas e itens de listas personalizadas.
2. Gerenciar campos personalizados, anexos, eventos de calendário
3. Criar e modificar fluxos de trabalho e processos de negócios

Exemplo prático:

Um cliente solicitou transferir os produtos de um pedido para dentro de uma tarefa. Em poucas horas, um webhook foi criado para copiar todas as linhas de produtos diretamente para a tarefa — ideal para empresas que vendem serviços e precisam transformá-los em tarefas após a aprovação da proposta.

Como funciona um Webhook?

Um webhook nada mais é do que um script hospedado em um servidor que você controla. O Bitrix24 se comunica com esse script por meio de uma URL (como se fosse uma página da web). Ao invés de exibir conteúdo visual, essa “página” executa ações com base nos dados recebidos.

Esse conceito é amplamente utilizado em sistemas de TI mais avançados. Ao contrário de CRMs “fechados”, que se vendem pela simplicidade, o Bitrix24 permite personalizações profundas através da API — o que significa integração real com o seu ecossistema de ferramentas.

Com a API do Bitrix24, você pode, por exemplo:

Webhooks são apenas scripts em execução em qualquer hospedagem que você confia e controla

• Integrar o CRM com sistemas de contabilidade
• Conectar com lojas online ou ERPs
• Trocar dados com os sistemas dos seus parceiros comerciais

Terminologia Essencial

Antes de mergulhar, é útil entender alguns termos:

No entanto, a coisa mais importante a saber agora é o arquivo JavaScript Object Notation. (JSON). Bem, JSON é um formato de dados genérico com um número mínimo de tipos de valor: cadeias de caracteres, números, booleanos, listas, objetos e nulos. Embora a notação seja um subconjunto do JavaScript, esses tipos são representados em todas as linguagens de programação comuns, tornando o JSON um bom candidato para transmitir dados através de lacunas de linguagem.

Veja como esse JSON pode se parecer:

Se você lê-lo, você encontrará rapidamente sua legibilidade. Olhe – esta é apenas uma ordem da Internet!

Boa notícia: você não precisa escrever JSON do zero, existem bibliotecas prontas que fazem isso por você! Então vamos parar de teorizar e começar a praticar?!

Mergulhe no Bitrix24 e no JSON

Deixe-me mostrar minha apresentação slide por slide onde descrevo como o webhook e o próprio Bitrix24 e JSON estão trabalhando juntos como uma equipe de Fórmula 1.

Aqui você pode ver todos os participantes: Bitrix24, Internet e um webhook.
B24 tem um formulário / cartão especial de Webhook de entrada. Você pode encontrá-lo pelo seguinte caminho: Recursos do desenvolvedor \ Outros \ Webhook de entrada.

Copie esse URL e cole-o no script do seu webhook. Exatamente como é mostrado aqui:

No script webhook, você inserirá essa URL manualmente. Essa URL será usada para enviar seus arquivos JSON. Este número após o ‘resto’ é o ID do usuário. Isso significa que seu webhook funcionará apenas em nome desse usuário. Recomendo usar o ID do seu super-admin. No campo “permissões”, você escolherá CRM, Tarefa ou outros módulos aos quais você concorda em dar permissão.

Então, agora a imagem da comunicação entre o seu webhook e o Bitrix24 é:

Imagine por um segundo que nosso webhook precisa saber a temperatura média em Paris e seu Bitrix24 tem essa informação.
Seu webhook enviará um arquivo JSON contendo [{ “city”: “Paris”, “units”: “C”}] para o Bitrix24 usando a URL secreta que descrevemos logo acima. E será que “imediatamente” terá a resposta como aquela: [{ “low”: “16”, “high”: “23”}]

Cool?
Analisamos a situação quando a iniciativa está do lado do webhook. Você queria saber a temperatura – você pergunta sobre isso a qualquer momento que você escolher. Mas e a situação quando você quer receber um alerta quando a temperatura é alterada? Ou subiu mais a “alta”. Para essas situações, o Bitrix24 tem outro formulário/cartão bem perto do cartão Webhook de entrada.
Você pode encontrá-lo pelo seguinte caminho: Recursos do desenvolvedor \ Outros \ Webhook de saída.

Aqui somos bem-vindos para fazer configurações manuais no lado de um Bitrix24. Informe ao B24 a URL do seu webhook.

A próxima coisa importante aqui é o campo “Eventos”. Por exemplo, em um dos vídeos, falei sobre o cálculo da Receita do Cliente. O webhook fazendo isso é bastante conveniente para chamar através do evento “Status da fatura atualizado”.

Este não é o único lugar onde você pode apontar para o evento que chamará seu webhook.

Outras formas de acionar webhooks:

1. Regras de automação no CRM
2. Regras de automação em Tarefas e Projetos
3. Atividades de workflow

É possível inclusive passar parâmetros personalizados, como e-mail ou ID do responsável, diretamente na URL.

Exemplo Prático: Verificação de E-mail

Exemplo: você quer verificar se o e-mail do lead retornado ao seu site é o e-mail “de trabalho” ou apenas algum parecido com o Gmail. Para essa verificação, você preparou um webhook e colocou sua URL na seção “Regras de automação” do seu estágio de pipeline chamada “Retornar ao site”. Você pode adicionar ao e-mail do lead de URL como um parâmetro. Como aqui:

Você pode ver que ‘e-mail’ e ‘responsável’ são variáveis que você pode facilmente buscar dentro do seu script e usar mais.

Para finalizar a imagem visual, aqui está o último slide:

O evento causa a chamada do seu webhook.
Webhook envia uma consulta-JSON e recebe a resposta-JSON.
É isso 😉

E agora?

Escolha sua linguagem de programação preferida. Escolhi PHP. Para escrever um script para o webhook, peguei o aplicativo Visual Studio. [BTW, links para todos os aplicativos mencionados aqui, você pode encontrar em uma descrição deste vídeo (basta rolar um pouco para baixo!).]

Para não escrever JSON sozinho, encontrei uma boa biblioteca. Agora posso usar muito simples adicionar, atualizar, excluir semântica para operar dados no Bitrix24! O script e links para a biblioteca você encontrará na descrição!

Então, o roteiro está pronto, né?! Agora devemos hospedá-lo em algum lugar. Obviamente, se você escrever seu código em PHP, você precisará de um hoster que possa lhe fornecer um servidor com um interpretador PHP, certo?!

O único cuidado da minha experiência: não use hospedagem gratuita. Livre significa livre – você nunca sabe quanto tempo você tem que esperar até que o webhook realmente atue.

Encontre seu cliente FTP favorito e use-o para:

1. Transfira seus webhooks para o “servidor”
2. Baixe arquivos de log do “servidor”.

O que os webhooks podem e não podem fazer

Webhooks podem ajudá-lo a integrar Bitrix24 com Prestashop, SAP SuccessFactors, Shopify, Microsoft Dynamics AX… a lista é ilimitada!

Ou olhe para isso:

• Automação do processamento de leads com aquecimento de leads “frios” por meio de fluxo de trabalho complexo.
• Integração do Bitrix24 com o Google Sheets e Google Data Studio.
• Criação de vários painéis para dados de vendas em várias moedas.
• Transformando produtos em tarefas.
• Criação automática de projeto/grupo quando o Negócio é movido para um determinado status.
• Fechamento de projetos com procedimentos gerados automaticamente, noções para clientes do cliente e notas fiscais.
• Automação do onboarding de leads (processamento de dados e acompanhamento dos casos em que o lead visita o site)
• Sistema de faturamento aleatório e periódico: transformando tarefas em negócios e faturas.

Esta é uma lista do que fiz pessoalmente para os clientes em apenas um mês, utilizando somente webhooks. O mais surpreendente é que, dois meses antes deste artigo, não tinha nenhuma experiência em PHP, hospedagem, FTP, entre outros. Um desenvolvedor criou nosso primeiro webhook e depois… sumiu. Para honrar meus compromissos com os clientes, tive que começar a desenvolver tudo por conta própria. O que isso tudo quer dizer? Que você pode alcançar o mesmo nível de habilidade que eu.

O que os webhooks NÃO podem fazer:

1. Fazer alterações na interface (incluindo novas interfaces como formulários, notificações personalizadas e assim por diante)
2. Faça qualquer coisa que não seja permitida pela API (por exemplo, você não pode ter acesso aos comentários do Negócio, e-mails, assinaturas de e-mail…)
3. Não te faça nem café nem… chá!

Recapitulação relâmpago

Finalmente, aqui estão apenas 6 obstáculos que você precisa superar para ser capaz de executar seu webhook:

1. Encontre uma hospedagem confiável
2. Defina os eventos que irão acionar o webhook
3. Instale uma biblioteca para facilitar a programação (se for PHP)
4. Escreva seu script
5. Suba os arquivos com um cliente FTP

Adições úteis

Vídeo “Como importar empresas, contatos e negócios para o Bitrix24“

Post “Bitrix24: conversão de Produtos em Tarefas webhook“

O código-fonte de um webhook “O script PHP calcula os pagamentos do cliente cuja fatura acabou de ser paga | Bitrix24” link para o GitHub e o código em si aqui:

<?php

    ini_set("log_errors", 1);
    ini_set("error_log", "./php-error.log");

    writeToLog($_REQUEST, 'incoming'); //comment it when everything will be debugged
    // 
    // This webhook should be called by Bitrix24 event '
    // Go to Your portal \ Developer resources \ Other \ Outbound webhook
    // or like it shown on the following screenshot: https://cloud.mail.ru/public/EmPS/BNuEV3s3p
    // 
    //=== CONSTANTS zone
    //
    define("UFRAS", "UF_CRM_XXXXXXXXX"); // The system name of custome field

    //=== VALIDATION & INITIALIZATION zone
    //Validates Webhook params and fill variables by Webhook params
    
    require __DIR__ . '/vendor/autoload.php';
    
    use \App\Bitrix24\Bitrix24API; // The library https://github.com/andrey-tech/bitrix24-api-php
    
    $webhookURL = 'https://[yourURLfromBitrix24]/';
    
    $bx24 = new Bitrix24API($webhookURL);
    
    $InvoiceID = $_REQUEST['data']['FIELDS']['ID'];
    
    //=== WORKING zone
    
    $InvoiceFields = $bx24->getInvoice($InvoiceID); //Get Invoice fields. 
    
    //If the Invoicee not just paid, then exit from the Webhook
    if ($InvoiceFields['PAYED'] != 'Y') {
        file_put_contents(getcwd() . '/hook.log', "\nInvvoice " . $InvoiceFields['ID'] . " is not paid \n", FILE_APPEND);
        exit;
    }
    
    if (!$Company) exit; //If no Company in Invoicee, exit.
    
    $Company = $InvoiceFields['UF_COMPANY_ID'];
    if (!$Company) exit; //If no Contact in Invoicee, exit.
    
    $CompanyFields = $bx24->getCompany($Company);
    
    //Which year is today?
    $CurrentYear = date("Y");
    $HappyThisYearString = $CurrentYear . '-01-01';
    $HappyThisYearTime = strtotime($HappyThisYearString);
    
    //=== WORKING ZONE
    
    //Summarize only this company's Invoice Amounts
    //First, let's get filtered invoices into an array
    $getInvoiceListGeneratorObject = $bx24->getInvoiceList(['ID' => 'ASC'],
    ['UF_COMPANY_ID' => $Company, 'PAYED' => 'Y'],
    ['ID', 'PRICE', 'DATE_PAYED', 'UF_DEAL_ID'],);
    //Invoice amounts into Array
    $InvoiceArray = array();
    foreach ($getInvoiceListGeneratorObject as $value) {
        $InvoiceArray = array_merge($InvoiceArray, $value);
    }
    
    //Summarize Invoice Amounts
    $m = count($InvoiceArray);
    if ($m == 0) {
        file_put_contents(getcwd() . '/hook.log', "\$no payments from this customer at all\n", FILE_APPEND);
        exit(json_encode(array('error' => 'no payments from this customer at all' )));
    }
    $RevenueCurrentYear = 0;
    for ($i = 0; $i < $m; $i++) {
        $t = strtotime($InvoiceArray[$i]['DATE_PAYED']);
        // file_put_contents(getcwd() . '/hook.log', "\n\$t = " . $t, FILE_APPEND);
        if ($t >= $HappyThisYearTime) {
            $RevenueCurrentYear += $InvoiceArray[$i]['PRICE'];
        }
    }
    if ($RevenueCurrentYear == 0) {
        file_put_contents(getcwd() . '/hook.log', "\n\$no payments from this customer this year\n", FILE_APPEND);
        exit(json_encode(array('error' => 'no payments from this customer this year' )));
    }
    
    $CompanyFields = $bx24->getCompany($Company);
    
    $bx24->updateCompany($Company, [UFRAS => $RevenueCurrentYear], ["REGISTER_SONET_EVENT" => "Y"]);
    
    //=== FUNCTIONS zone
    function writeToLog($data, $title = '') {
            $log = "\n------ max2SumInvoices.php ------------------\n";
            $log .= date("Y.m.d G:i:s") . "\n";
            // $log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
            // $log .= print_r($data, 1);
            file_put_contents(getcwd() . '/hook.log', $log, FILE_APPEND);
            return true;
    }

Se você leu até aqui, parabéns! Você já está pronto para potencializar o Bitrix24 da sua empresa com automações sob medida.

Vamos juntos acelerar seus processos e resultados?