Developers
Criar chave de APIEntrar na plataforma

Webhooks de entrada

Inicie um Workflow da Astrify Flows a partir de qualquer sistema com o gatilho Receber webhook, modo escuta e exemplo de JSON.

O gatilho Receber webhook dos Workflows cria uma URL só sua. Qualquer sistema que chame essa URL (seu site, ERP, loja, n8n, Make, Zapier…) inicia o Workflow com os dados enviados. Não precisa de chave de API.

Configurar

  1. Na plataforma, crie ou abra um Workflow e escolha o gatilho Receber webhook (grupo Webhook e API).

  2. Salve o Workflow. A URL do webhook só aparece depois de salvar; ela é gerada pelo servidor e tem este formato:

    https://api2.astrify.com.br/api/webhooks/workflow/{token}
  3. Clique em Escutar webhook e, nos 2 minutos seguintes, envie uma chamada de teste do seu sistema. O primeiro evento que chegar é capturado sem executar o fluxo e aparece em Eventos recebidos, para você ver o formato real antes de montar as etapas.

  4. Monte as etapas usando os campos recebidos como variáveis e ative o Workflow.

Enviar dados

A URL aceita POST, PUT, PATCH e GET. O corpo pode ser JSON, formulário (application/x-www-form-urlencoded) ou texto, com até 256 KB.

Terminal window
curl -X POST "https://api2.astrify.com.br/api/webhooks/workflow/SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"nome": "Maria Oliveira",
"email": "maria@exemplo.com",
"telefone": "5511900000000",
"pedido": { "numero": 1234, "valor": 199.90, "status": "pago" }
}'

Resposta quando o Workflow está ativo (o fluxo roda em segundo plano):

{ "success": true, "modo": "producao", "evento_id": "22222222-2222-2222-2222-222222222222" }

Resposta durante o modo escuta:

{ "success": true, "modo": "teste", "mensagem": "Evento capturado. O fluxo não foi executado (modo escuta)." }

Usar os dados no fluxo

O que chega fica disponível nas variáveis do gatilho:

Variável Conteúdo
{{trigger.dados.body}} O corpo inteiro
{{trigger.dados.body.pedido.numero}} Um campo do corpo (no exemplo acima, 1234)
{{trigger.dados.query}} Os parâmetros da URL (query string)
{{trigger.dados.headers}} Os cabeçalhos recebidos
{{trigger.dados.method}} O método HTTP

Por segurança, os cabeçalhos Authorization, Cookie, X-Api-Key, X-Session-Token e Proxy-Authorization são descartados e não ficam guardados.

Qual lead é este?

No painel do gatilho, em Qual lead é este? (opcional), informe onde estão o e-mail e o telefone no que chega (por exemplo body.email e body.telefone). O Workflow procura o lead existente da sua empresa por esses dados (primeiro pelo e-mail) e as etapas de CRM passam a agir nele. O campo do nome tem o padrão body.nome.

Sem essa indicação, ou se nenhum lead for encontrado, o fluxo roda sem lead e as etapas de CRM avisam que não há lead. Para criar o lead a partir do webhook, use o modelo pronto Receber lead por webhook.

Eventos recebidos

Cada chamada, de teste ou de produção, aparece em Eventos recebidos, com o corpo, os parâmetros da URL, os cabeçalhos e a situação:

  • Executado: o fluxo rodou (a execução também aparece no histórico do Workflow).
  • Ignorado: o fluxo não rodou, por exemplo porque o Workflow está desativado, a etapa de webhook foi apagada, os Workflows estão pausados ou o limite mensal de execuções do plano foi atingido. O evento capturado no modo escuta também aparece como ignorado.
  • Erro: algo falhou ao iniciar a execução.

A plataforma guarda os 50 eventos mais recentes de cada gatilho.

Limites e respostas de erro

Status Quando
200 Evento recebido (o retorno não espera o fluxo terminar)
400 Content-Length inválido
404 URL (token) inexistente: Webhook não encontrado
413 Corpo maior que 256 KB
429 Mais de 120 chamadas por minuto na mesma URL, ou mais de 600 por minuto do mesmo IP: Muitas chamadas: aguarde um minuto

Alternativa autenticada: evento da API

Se a sua integração já usa a API aberta, você pode disparar Workflows com a chave de API em vez de uma URL pública. No Workflow, use o gatilho Evento da API aberta (opcionalmente com um nome de evento) e chame:

Terminal window
curl -X POST https://api2.astrify.com.br/v1/workflows/eventos \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d '{"evento":"pedido_pago","email":"maria@exemplo.com","dados":{"pedido":1234,"valor":199.90}}'
  • Escopo: workflows:write.
  • evento: de 1 a 60 caracteres minúsculos (letras, números, _, . e -). Dispara os Workflows com esse nome de evento e os que não definiram nome.
  • Informe o lead por lead_id ou email; o lead precisa existir na sua empresa (senão, 404).
  • dados: objeto de até 20 KB, disponível nas variáveis api_evento e api_dados da execução.
  • Acompanhe as execuções em GET /v1/workflows/{workflow_id}/execucoes.

Digite para pesquisar em toda a documentação.