Configurar um gatilho de webhook

Receba dados de serviços externos para acionar fluxos de trabalho.

Gatilhos de webhook permitem que serviços externos iniciem seus fluxos de trabalho enviando dados para uma URL exclusiva. Use-os para conectar formulários, aplicativos de terceiros e integrações personalizadas.

Quando usar webhooks

Configuração passo a passo

Etapa 1: criar o fluxo de trabalho

1. Vá para Configurações → Fluxos de trabalho.
2. Clique em + Novo fluxo de trabalho.
3. Dê um nome (por exemplo, “Envio de formulário do site”).

Etapa 2: configurar o gatilho de webhook

1. Clique no bloco de gatilho.
2. Selecione Webhook.
3. Você receberá uma URL de webhook exclusiva, como: https://sua-instancia/webhooks/workflow/abc123...
4. Copie esta URL — você vai precisar dela no seu serviço externo.

Etapa 3: definir a estrutura de dados esperada

Para solicitações POST, defina a estrutura esperada do corpo:

1. Clique em Definir corpo esperado.
2. Insira um JSON de exemplo que corresponda ao que o seu serviço enviará:

{
  "firstName": "João",
  "lastName": "Silva",
  "email": "joao@exemplo.com.br",
  "company": "Comércio Andrade",
  "message": "Tenho interesse no seu produto"
}

3. Clique em Salvar — isso cria variáveis que você pode usar nas etapas subsequentes.

Etapa 4: adicionar ações

Agora adicione ações que usem os dados do webhook.

Exemplo: criar um registro de Pessoa

1. Adicione a ação Criar registro.
2. Selecione o objeto Pessoas.
3. Mapeie os campos:

Etapa 5: testar o webhook

Antes de ativar, teste o seu webhook.

Usando cURL:

curl -X POST https://sua-instancia/webhooks/workflow/abc123... \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Teste","lastName":"Usuário","email":"teste@exemplo.com.br"}'

Usando o Postman ou similar:

1. Crie uma solicitação POST para a sua URL de webhook.
2. Defina o cabeçalho Content-Type como application/json.
3. Adicione o corpo JSON de teste.
4. Envie e verifique as execuções do fluxo de trabalho.

Etapa 6: ativar

Depois de testar, clique em Ativar para ativar o fluxo de trabalho.

Como lidar com diferentes estruturas de dados

Dados aninhados

Se o seu webhook enviar dados aninhados:

{
  "contact": {
    "name": "João Silva",
    "email": "joao@exemplo.com.br"
  },
  "source": "site"
}

Referencie com: {{trigger.body.contact.email}}

Arrays

Se os dados incluírem arrays:

{
  "items": [
    {"name": "Produto A", "qty": 2},
    {"name": "Produto B", "qty": 1}
  ]
}

Como você lida com arrays depende do seu caso de uso.

Número desconhecido de itens → use o Iterador. Se você precisar processar cada item no array (por exemplo, criar um registro para cada), adicione uma ação Código para analisar o array e, em seguida, use o Iterador:

export const main = async (params: { items: any }) => {
  const items = typeof params.items === "string"
    ? JSON.parse(params.items)
    : params.items;
  return { items };
};

Em seguida, use o Iterador para percorrer: {{code.items}}

Campos conhecidos/específicos → extraia para campos nomeados. Se o array contiver campos específicos aos quais você deseja acessar individualmente (por exemplo, respostas de formulário em que a posição 0 é sempre “nome”, a posição 1 é sempre “sobrenome”), adicione uma ação Código para extraí-los:

export const main = async (params: { items: any }) => {
  const items = typeof params.items === "string"
    ? JSON.parse(params.items)
    : params.items;
 
  return {
    product: {
      name: items[0]?.name || "",
      qty: items[0]?.qty || 0
    }
  };
};

Agora você pode selecionar product.name e product.qty individualmente nas etapas subsequentes.

Para mais detalhes sobre como lidar com arrays, consulte Tratar arrays em ações de código.

Relacionados

• Gatilhos de fluxo de trabalho
• Ações de fluxo de trabalho