webhook-integration

O submódulo Webhook Integration é a espinha dorsal de automação do HedHog, viabilizando fluxos orientados a eventos em ambas as direções: receber payloads arbitrários de sistemas externos e despachar ações ou notificações quando eventos de domínio internos ocorrem.

A cada integração de webhook de entrada é atribuído um UUID único que forma sua URL de recebimento: POST /webhook/:uuid. Sistemas externos — provedores de pagamento, serviços de formulários, pipelines de CI/CD, dispositivos IoT — podem enviar (POST) qualquer payload JSON para essa URL. O servidor valida uma assinatura HMAC opcional (usando o secret da integração contra o corpo bruto da requisição) e passa o payload pelo pipeline ordenado de ações da integração.

Um pipeline de ações é uma sequência de ações que executam em ordem quando o webhook é disparado. Cinco tipos de ação estão disponíveis. Email envia uma mensagem transacional usando um template do submódulo Mail, com os campos do payload substituídos nas variáveis do template. HTTP Request realiza uma chamada de saída para qualquer URL com método, headers, corpo, timeout e número de tentativas configuráveis. Internal API chama um endpoint do HedHog por caminho, permitindo operações disparadas por webhook, como criar registros ou gerar relatórios. App Command despacha um comando de aplicação registrado por slug com parâmetros tipados, desacoplando o handler do webhook de detalhes específicos de implementação. WhatsApp via Evolution API envia uma mensagem para um número de telefone ou grupo por meio de um integration profile do Evolution configurado.

Os webhooks de saída baseados em eventos (event-webhook) se inscrevem em eventos de domínio do catálogo de eventos de integração e entregam o payload do evento a uma URL externa configurada sempre que o evento é disparado. É assim que o HedHog envia dados para sistemas externos: quando um usuário é criado, uma compra é concluída ou um status muda, os event webhooks inscritos são notificados em tempo quase real por meio do processador de outbox.

Cada integração de webhook carrega um UUID (usado na URL de recebimento) e um secret (usado para validação HMAC). Ambos podem ser regenerados de forma independente por endpoints dedicados, sem recriar a integração nem perder suas definições de ações, dando suporte à rotação de credenciais sem downtime. POST /webhook-integration/:id/duplicate clona uma integração, incluindo todas as suas ações, simplificando a criação de pipelines de automação semelhantes.

Cada invocação é registrada em log. GET /webhook-integration/:id/log retorna os logs históricos paginados. GET /webhook-integration/:id/log/stream abre um stream de Server-Sent Events para depuração em tempo real, tornando possível rastrear falhas e verificar as transformações de payload sem recorrer a uma ferramenta externa de observabilidade.