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:
- Webhooks de saída (em Configurações → Webhooks): eventos de e-mail marketing, assinados com HMAC e com retentativas.
- 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.1Content-Type: application/jsonUser-Agent: Astrify-Webhooks/1.0X-Astrify-Event: email.clickedX-Astrify-Delivery: 12345X-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.sucessoehttp.respostapara 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.