Webhook

O trigger Webhook executa um workflow sempre que uma requisição HTTP de entrada chega a uma URL que o Zoen gera para ele. Use-o para iniciar um workflow a partir de qualquer serviço externo ou app customizado que possa enviar uma requisição HTTP — quando não existe um trigger de integração dedicado.

Como funciona

Adicione o trigger Webhook como ponto de entrada do workflow.
Copie a URL única de webhook que o Zoen gera.
Aponte seu serviço externo para ela com um POST.
Cada requisição à URL executa o workflow, com o payload da requisição disponível adiante.

Configuração

Input Format

Opcionalmente defina o formato JSON que você espera. Os campos ficam documentados no bloco e são lidos adiante pelo nome. Use um campo file[] para uploads.

Autenticação

Ative Require Authentication e defina um token. Callers o enviam como Bearer token no header Authorization, ou você nomeia um header customizado (como X-Secret-Key) e o token é comparado com esse header.

Resposta

Por padrão o endpoint confirma o recebimento. Mude para uma resposta customizada para devolver seu próprio status code e corpo JSON ao caller.

Saídas

A requisição é parseada e fica disponível para o resto do workflow — os campos do body pelo nome (um userId no body é lido como <webhook.userId>), além dos headers e query parameters da requisição. Campos comuns como event, id e data são extraídos do payload quando presentes.

Comportamento

Deduplicação — checagens de idempotência impedem execuções duplicadas de requisições idênticas repetidas.
Rate limiting — proteção embutida contra abuso.
Deploy obrigatório — a URL só dispara depois que o workflow está publicado; caso contrário retorna not-found.
Sem auto-desativação — diferente de triggers de polling (RSS, Gmail, IMAP), um webhook push processa cada requisição de forma independente e não se desativa após execuções falhas.

Valide e sanitize os dados de webhook recebidos antes de usá-los adiante.

Teste

Envie uma requisição para a URL do webhook com curl (ou Postman) e veja a execução aparecer em Logs:

curl -X POST "<your webhook URL>" \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "userId": "123"}'

Abra a execução para confirmar que o payload chegou do jeito que os blocos seguintes esperam — que <webhook.userId> resolve, e que a autenticação rejeita uma requisição sem o token se você a ativou.

Triggers de serviço

Muitas integrações também podem atuar como triggers: ative Use as Trigger em um bloco de serviço (Slack, GitHub, Stripe e mais) para registrar um webhook específico do serviço com filtro de eventos e dados estruturados — sem endpoint genérico para configurar.

Veja Triggers para todos os serviços que suportam isso.

Common Questions

POST dispara workflows. GET é usado só para challenges de verificação específicos do provedor (como Microsoft Graph ou WhatsApp). Outros métodos retornam 405 Method Not Allowed.

Ative Require Authentication e defina um Authentication Token. Callers o enviam como Bearer token no header Authorization, ou você especifica um nome de header customizado (ex.: X-Secret-Key) e o token é comparado com esse header.

Sim. O campo Input Format permite definir o schema JSON esperado. É opcional, mas documenta a estrutura, e você pode usar um campo file[] para uploads.

Sim. O pipeline de processamento inclui checagens de idempotência que impedem execuções duplicadas de requisições repetidas com o mesmo payload.

Todos — headers, body e query parameters são parseados e ficam disponíveis para os blocos seguintes. Campos comuns como event, id e data são extraídos do payload quando presentes.

Sim. O endpoint verifica se o workflow está publicado antes de disparar uma execução; caso contrário retorna not-found.

Não. Diferente de triggers baseados em polling (RSS, Gmail, IMAP), webhooks push não se desativam automaticamente — cada requisição é processada de forma independente. Se as execuções falharem de forma consistente, confira os logs das execuções.

Webhook

Common Questions

On this page