Developers
Criar chave de APIEntrar na plataforma

Webhooks de saída

Receba eventos de e-mail marketing da Astrify Flows assinados com HMAC e envie outros dados com o bloco Disparar webhook do Workflow.

A Astrify Flows envia dados para o seu sistema de duas formas:

  1. Webhooks de saída (em Configurações → Webhooks): eventos de e-mail marketing, assinados com HMAC e com retentativas.
  2. Blocos do Workflow Disparar webhook e Requisição HTTP: para tudo o mais (lead que mudou de etapa, conversa, pedido etc.), você monta um Workflow com o gatilho desejado e a etapa que chama a sua URL.

Webhooks de saída (e-mail marketing)

Cadastre a URL em Configurações → Webhooks e escolha os eventos. São até 10 endpoints por empresa. O segredo de assinatura (começa com whsec_) é mostrado uma vez, na criação. Só usuários com permissão de configurar webhooks no cargo gerenciam os endpoints; chaves de API não gerenciam webhooks.

Eventos

Evento Quando acontece
email.opened E-mail marketing aberto (primeira abertura)
email.clicked Clique em link ou botão do e-mail (o primeiro de cada pessoa em cada link)
email.replied Contato respondeu a um e-mail de campanha (primeira resposta)
email.unsubscribed Contato cancelou a inscrição
email.bounced E-mail devolvido (bounce)
email.complaint Contato marcou como spam
email.list_joined Contato entrou numa lista de e-mail (formulário, preferências ou importação confirmada)
teste.ping Teste de conexão, enviado pelo botão de teste da tela

Não há outros eventos de saída: lead, negócio, conversa, Quadros e Workflows não geram webhooks de saída. Para esses casos, use o bloco Disparar webhook.

A requisição

Cada evento chega como um POST com corpo JSON:

POST /sua-url HTTP/1.1
Content-Type: application/json
User-Agent: Astrify-Webhooks/1.0
X-Astrify-Event: email.clicked
X-Astrify-Delivery: 12345
X-Astrify-Signature: t=1763210000,v1=5f2b…
{
"id": "evt_0123456789abcdef0123456789abcdef",
"evento": "email.clicked",
"criado_em": "2026-11-15T12:00:00+00:00",
"empresa_id": "00000000-0000-0000-0000-000000000000",
"dados": { "…": "dados do evento" }
}

O envelope (id, evento, criado_em, empresa_id, dados) é o mesmo para todos os eventos; o conteúdo de dados muda conforme o evento. Use a tela de entregas ou o botão de teste para ver um exemplo real.

Validar a assinatura

O cabeçalho X-Astrify-Signature tem o formato t=<timestamp unix>,v1=<hex>, em que v1 = HMAC-SHA256(segredo, "<t>.<corpo bruto>"). Recalcule com o corpo exatamente como chegou, compare em tempo constante e rejeite se t tiver mais de 5 minutos de diferença do seu relógio (impede que uma entrega capturada seja repetida).

import crypto from 'node:crypto';
export function assinaturaValida(segredo, cabecalho, corpoBruto) {
const partes = Object.fromEntries(cabecalho.split(',').map((p) => p.split('=')));
const t = Number(partes.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const esperado = crypto.createHmac('sha256', segredo).update(`${t}.`).update(corpoBruto).digest('hex');
const recebido = partes.v1 || '';
return recebido.length === esperado.length &&
crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido));
}
import hashlib, hmac, time
def assinatura_valida(segredo: str, cabecalho: str, corpo_bruto: bytes) -> bool:
try:
partes = dict(p.split("=", 1) for p in cabecalho.split(","))
t = int(partes["t"])
except (ValueError, KeyError):
return False
if abs(time.time() - t) > 300:
return False
esperado = hmac.new(segredo.encode(), f"{t}.".encode() + corpo_bruto, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperado, partes.get("v1", ""))

Entregas e retentativas

  • Responda com qualquer status 2xx em até 8 segundos. Processe o evento depois, numa fila.
  • Se a entrega falhar, a Astrify tenta de novo depois de 1 min, 5 min, 30 min, 2 h e 6 h. Depois disso a entrega fica esgotada e pode ser reenviada pela tela.
  • Com 10 entregas esgotadas seguidas, o endpoint é desativado.
  • O mesmo evento pode chegar mais de uma vez: use o id (evt_…) para ignorar repetidos.
  • A URL precisa ser pública (endereços internos e privados são recusados).

Bloco Disparar webhook do Workflow

Para enviar outros dados ao seu sistema, crie um Workflow com o gatilho que interessa (por exemplo Lead criado, Lead mudou de etapa, Proposta aceita, Card concluído, Novo pedido ou Nova conversa no canal) e acrescente a etapa Disparar webhook. Ela faz um POST com JSON para a sua URL com os dados do lead e do atendimento:

{
"evento": "chatbot.webhook",
"lead": {
"id": "33333333-3333-3333-3333-333333333333",
"nome": "Maria Oliveira",
"telefone": "5511900000000",
"email": "maria@exemplo.com",
"empresa_id": "00000000-0000-0000-0000-000000000000"
},
"contato": {
"id": "44444444-4444-4444-4444-444444444444",
"nome": "Maria Oliveira",
"whatsapp": "5511900000000",
"email": "maria@exemplo.com"
},
"conversa": { "id": null, "canal": null, "instancia_id": null },
"dados": { "origem": "workflow-pos-venda" }
}
  • Em Dados extras (JSON) você acrescenta o objeto dados, com variáveis do fluxo (ex.: {{nome}}).
  • Em Cabeçalhos você envia autenticação para o seu sistema, por exemplo Authorization: Bearer seu_token.
  • Aguardar resposta: o fluxo espera até 20 segundos e disponibiliza http.status, http.sucesso e http.resposta para as condições. Disparar e seguir: o fluxo continua na hora, sem resposta.

Requisição HTTP

A etapa Requisição HTTP chama qualquer API externa com o método que você escolher, cabeçalhos e corpo JSON com variáveis (o corpo é ignorado em GET). A resposta pode ser salva numa variável (Salvar resposta na variável) e usada nas próximas etapas, por exemplo como {{resposta_api}}. Com Aguardar resposta, o tempo limite é de 20 segundos.

Digite para pesquisar em toda a documentação.