Webhooks: receba e responda eventos em tempo real

A maioria das integrações funciona no modelo de consulta (polling): o fluxo roda de forma agendada e pergunta ao sistema externo se há algo novo desde a última verificação, processa a resposta e segue. Esse modelo funciona perfeitamente para dados que não exigem reação imediata. No entanto, quando o evento precisa acionar o processo no exato momento em que acontece, a lógica se inverte para o modelo em tempo real (real-time).

Nas Integrações Pipefy, a forma como os gatilhos (triggers) foram implementados dentro dos conectores determina como essa captura acontece na prática, dividindo-se em três cenários claros:

• Triggers de Consulta Agendados (Polling): Sob o capô, o conector dedicado realiza uma varredura periódica automatizada. O fluxo "bate na porta" da API externa de tempos em tempos (ex: a cada hora ou a cada 15 minutos) para analisar se existem novos dados gerados para disparar o flow.
• Triggers em Tempo Real Nativos (Webhooks): São conectores dedicados que já possuem a inteligência de escuta ativa integrada de forma transparente. Eles realizam a assinatura no sistema externo automaticamente e disparam o evento em tempo real na plataforma assim que a ação acontece no parceiro.
• Capturar Webhook (Gatilho Genérico): É a peça curinga de tempo real da plataforma. Você deve usar a opção genérica de Capturar Webhook em duas situações específicas: quando o sistema com o qual você quer se integrar suporta o envio de dados instantâneos, mas não existe um conector dedicado para ele nas Integrações Pipefy; ou quando o conector dedicado daquele sistema só foi implementado pela engenharia no modelo de consulta (polling), mas a sua operação exige obrigatoriamente uma reação imediata. Ao usá-lo, as Integrações Pipefy geram uma URL exclusiva para você colar no sistema externo e forçar o disparo instantâneo.

📖  O que você vai entender aqui:

Assíncrono ou síncrono: o webhook que responde de volta

A maioria dos webhooks funciona de forma assíncrona: o sistema externo dispara o evento, o  Integrações Pipefy confirma o recebimento instantâneo com um código de status HTTP 200 e processa o fluxo em segundo plano, sem que o chamador precise aguardar o resultado. O sistema parceiro segue em frente independentemente do desfecho do processo.

O webhook síncrono altera esse contrato de comunicação. Quando a URL gerada pelo gatilho é configurada com o sufixo /sync em seu endpoint, o fluxo processa todas as ações sequenciais e retorna uma resposta estruturada ao sistema de origem antes de encerrar a conexão. O chamador aguarda ativamente na linha. Isso viabiliza um padrão arquitetural diferente: o Integrações Pipefy deixa de ser apenas um receptor passivo de eventos e passa a agir como uma API customizada, devolvendo dados processados em tempo real para o sistema externo.

Quando o webhook síncrono faz sentido

Fluxos de validação e enriquecimento de dados em tempo real são os principais casos de uso para essa abordagem:

• Validação Cadastral: Um formulário externo de onboarding que precisa consultar a base do Pipefy e saber, antes de avançar para a próxima tela, se um CPF já está registrado.
• Checagem de Estoque: Uma plataforma de e-commerce que envia uma requisição síncrona para confirmar a disponibilidade de um item antes de autorizar o fechamento do pedido de um cliente.

Nesses cenários, o retorno imediato dos dados é mandatório. Para que a resposta estruturada seja enviada de volta ao sistema de origem, você deve obrigatoriamente incluir um passo do conector Webhook no final do seu fluxo utilizando a ação Return Response.

⚠ Cuidados críticos, Timeouts e Testes

• O Limite dos 30 segundos (HTTP 408): Webhooks síncronos exigem processamento ultra-rápido. Se o seu fluxo contiver muitas ações encadeadas, loops complexos ou consultas a APIs terceiras lentas que façam a execução demorar mais de 30 segundos, o Pipefy interromperá a espera e devolverá automaticamente um erro 408 Request Timeout para o sistema chamador. Mantenha o processamento síncrono estritamente enxuto.
• Uso de Error Handling como Contingência: Se qualquer passo quebrar no meio do caminho, o fluxo será interrompido. Utilize o recurso nativo de Error Handling nos nós críticos para capturar falhas pela rota de Falha e garantir que uma resposta amigável (via ação Return Response) seja entregue ao chamador, em vez de deixar a requisição morrer.
• Diferença entre URL ao Vivo e URL de Teste: * Ambiente Publicado (URL ao vivo): Aciona o fluxo real em produção e processa os dados vivos.
  • Ambiente de Desenvolvimento (/test): Para homologar sua integração durante a construção, adicione o sufixo /test ao final da URL do seu webhook. Isso permite que você envie requisições para gerar dados demonstrativos no painel e mapear o Data Selector com segurança, sem ativar as ações do fluxo publicado.

Caso de uso: Consulta em Tempo Real de Aprovação de Processos (ERP × Pipefy)

Um comprador está prestes a fechar um contrato de alto valor com um fornecedor dentro do ERP da empresa (como SAP ou Totvs). No entanto, por governança de conformidade (compliance), o ERP precisa garantir que a solicitação de compra e o orçamento já foram formalmente revisados e aprovados pela diretoria dentro do Pipe de Compras do Pipefy antes de liberar a assinatura do contrato.

Como a integração funciona na prática:

1. O Disparo Síncrono: No momento em que o comprador clica em "Gerar Contrato" no ERP, o sistema envia um webhook síncrono para o Pipefy Integrations carregando o ID do processo ou o código do projeto.
2. O Pipefy no Centro da Decisão: O fluxo utiliza o conector nativo do Pipefy para localizar instantaneamente o Card correspondente dentro do Pipe de Compras.
3. Checagem de Fase Viva: O fluxo analisa em qual fase o Card está posicionado (ex: se já migrou para a fase "Aprovado pela Diretoria") e extrai os dados preenchidos no histórico (como o nome do aprovador e a data da assinatura digital).
4. A Resposta Estruturada: Utilizando a ação Return Response do conector de Webhook, a integração devolve os dados em formato JSON para o ERP em menos de 30 segundos.
5. Fim do Fluxo no ERP: Se o retorno indicar que o Card no Pipefy está aprovado, o ERP libera a emissão do contrato na hora. Se o Card ainda estiver em triagem, auditoria ou tiver sido recusado, o ERP bloqueia a tela do comprador exibindo o motivo real do processo do Pipefy.

Por que esse modelo é o estado da arte?

Sem o webhook síncrono, o time de TI teria que construir uma API proprietária complexa ou o ERP precisaria ficar rodando consultas exaustivas de tempos em tempos (polling) para saber se o time finalizou o processo no Pipefy.

Com o Pipefy Integrations, o fluxo humano de trabalho, a governança e a tomada de decisão que acontecem no dia a dia do Pipefy se transformam, de forma nativa e sem código, em uma API viva e consultável para qualquer software da empresa.

Autenticação: o requisito que não é opcional

Um gatilho Webhook gera uma URL pública. Qualquer sistema que conheça essa URL pode disparar o fluxo. Sem uma camada de proteção ativa, um payload malicioso ou um disparo acidental de um sistema não autorizado executará o flow com os mesmos privilégios de uma chamada legítima.

Para mitigar esse risco, as Integrações Pipefy oferecem quatro opções de autenticação no gatilho Webhook, permitindo adequar a segurança à capacidade técnica do sistema parceiro:

• None (Nenhuma): O endpoint fica totalmente exposto. Esta opção só é aceitável durante testes controlados ou em janelas de desenvolvimento homologadas.
• Basic Auth: Exige uma combinação tradicional de usuário e senha. É o modelo ideal para integrar com sistemas legados ou ERPs comerciais que não oferecem suporte a cabeçalhos customizados ou tokens avançados.
• Header Auth: A abordagem mais comum e prática para ambientes produtivos. O sistema de origem inclui um cabeçalho específico com um valor secreto pré-combinado (como um Token Bearer), e o fluxo só inicia o processamento se o valor recebido for idêntico ao esperado.
• HMAC Signature: É o nível de segurança mais rigoroso para o tráfego corporativo de webhooks (padrão utilizado por plataformas como Stripe, Shopify e GitHub). O sistema externo gera uma assinatura criptográfica baseada no conteúdo exato do payload usando uma chave secreta compartilhada. Ao receber a chamada, as Integrações Pipefy recalculam esse código criptográfico para garantir a autenticidade do remetente e certificar que a mensagem não sofreu nenhuma alteração ou interceptação no caminho.

Antes de colocar em produção

• Use a URL com sufixo /test para validar o payload recebido sem executar as ações do flow. Confirme o formato e os campos antes de acionar a lógica real.
• Documente o contrato do webhook: quais campos o sistema de origem envia, qual formato, qual autenticação. Esse contrato é o ponto de falha mais comum quando o sistema de origem muda.
• Para webhooks síncronos, meça o tempo de processamento do flow em ambiente de teste antes de ir para produção. Identifique o timeout do sistema chamador e garanta que o flow completa dentro desse limite.
• Considere o comportamento do flow quando receber um payload inesperado ou mal formatado. Um Router que verifica a estrutura dos dados antes de processar protege o flow contra entradas inválidas.

Checklist de conclusão 

☐  A diferença entre webhook assíncrono e síncrono, e quando cada um se aplica

☐  Por que autenticação não é opcional em webhooks de produção

☐  Como usar a URL /test para validar o payload antes de executar o flow