Ação — enviar webhook

A ação send_webhook dispara uma requisição HTTP pra qualquer URL externa quando a automação executa. É a forma mais flexível de integrar o Syncro com sistemas externos que você usa: ERP, contabilidade, BI, ferramentas de email marketing, custom apps próprias.

Webhook é a "linguagem universal" de integração — quase todo sistema moderno aceita receber dados via HTTP.

Casos de uso

• Lead ganho → POST pra ERP criar pedido.
• Lead criado → POST pra Mailchimp adicionar contato.
• Tag aplicada → POST pra Slack notificar canal.
• Conversa encerrada → POST pra BI registrar métrica.
• Aniversário cliente → POST pra plataforma de email marketing disparar campanha.

Pré-requisitos

• Permissão de admin ou manager.
• URL externa que você controle ou tenha permissão de enviar dados.

Configurar webhook

Ao adicionar a ação send_webhook na automação:

URL

URL completa do webhook. Ex:

• https://api.minhaempresa.com/webhooks/leads
• https://hook.zapier.com/hooks/catch/123/abc
• https://n8n.minhaempresa.com/webhook/abc-123

⚠️ Atenção: o Syncro bloqueia URLs internas (localhost, 127.0.0.1, 192.168.x, 10.x, IPs metadata) pra prevenir SSRF (security). Se você precisa enviar pra rede interna, use proxy reverso público.

Método HTTP

• POST (default) — recomendado pra dados.
• PUT — quando atualiza recurso específico.
• PATCH — atualização parcial.
• DELETE — remove recurso.
• GET — consulta (incomum em webhook).

Headers

Lista de chave/valor pra enviar no header HTTP. Exemplos comuns:

Header	Valor típico	Pra que serve
Authorization	Bearer {token} ou Basic {base64}	Autenticação
Content-Type	application/json (default)	Indicar tipo do body
X-Source	syncro-crm	Origem (custom)
X-Tenant-Id	{{tenant.id}}	Identificação multi-tenant

Você adiciona cada header clicando em Adicionar header.

💡 Dica: tokens de autenticação devem ser mantidos em segredo. Não compartilhe URLs com tokens em hardcoded — use variáveis se possível.

Body — 2 modos

Modo Builder (visual)

Mais simples. Você adiciona campos com:

• Chave (key): nome do campo no JSON enviado.
• Source: de onde vem o valor.
• Value (opcional): pra valores literais.

Sources disponíveis:

Source	Tipo	Exemplo
lead.name	string	Nome do lead
lead.email	string	Email
lead.phone	string	Telefone
lead.company	string	Empresa
lead.value	number	Valor R$
lead.source	string	Origem
lead.tags	array	Tags em JSON
lead.stage_name	string	Nome da etapa
lead.pipeline_name	string	Nome do funil
lead.assigned_user_name	string	Nome do responsável
custom:42	typed	Custom field #42
tenant.name	string	Nome do tenant
tenant.id	int	ID do tenant
system.now_iso	string	Data/hora ISO 8601
system.now_unix	int	Timestamp Unix
system.trigger_type	string	Tipo do gatilho
literal	any	Valor fixo (value é usado)

Exemplo de body builder:

{
 "lead_id": "{{lead.id}}",
 "name": "{{lead.name}}",
 "email": "{{lead.email}}",
 "value": "{{lead.value}}",
 "tenant_name": "{{tenant.name}}",
 "received_at": "{{system.now_iso}}",
 "trigger": "{{system.trigger_type}}"
}

JSON é gerado automaticamente.

Modo Raw (JSON cru)

Pra controle total, escolha Raw e digite o JSON manualmente:

{
 "event": "lead_won",
 "data": {
 "name": "{{lead.name}}",
 "email": "{{lead.email}}",
 "amount": "{{lead.value}}",
 "metadata": {
 "tenant": "{{tenant.name}}",
 "timestamp": "{{system.now_iso}}"
 }
 }
}

Com interpolação {{...}} em qualquer valor.

💡 Dica: use Raw quando precisa de estruturas aninhadas (objetos dentro de objetos) ou formato específico que sistema externo exige.

Testar webhook

Antes de ativar a automação, teste o webhook:

1. Configure webhook (URL, headers, body).
2. Clique em Testar webhook.
3. Sistema envia o payload com o lead mais recente da sua conta.
4. Resultado aparece:

• Sucesso: status HTTP 2xx + texto curto da resposta.
• Falhou: erro detalhado (timeout, 4xx, 5xx, SSRF).

Se não tiver leads na conta, aparece: "Não há leads na conta para testar. Crie um lead primeiro.".

Como o webhook é processado (fluxo)

1. Automação dispara → cria registro do trabalho.
2. Sistema enfileira DispatchAutomationWebhookJob (assíncrono).
3. Job executa WebhookDispatcherService::dispatch:

• Valida URL (anti-SSRF).
• Interpola headers e body com contexto do lead/tenant/sistema.
• Envia HTTP via cliente Laravel.

4. Resposta:

• 2xx: sucesso. Cria evento webhook_sent na timeline com status + duration.
• 4xx/5xx: erro do servidor. Cria evento webhook_failed com detalhe.

5. Retry:

• Em erro de transporte (timeout, DNS, conexão recusada): tenta de novo com backoff exponencial 10s, 60s, 300s.
• Em 4xx/5xx: não retenta (problema do servidor externo).

Timeout e limites

• Timeout: 15 segundos.
• Sem redirects: se URL retorna 301/302, falha.
• Sem cookies: webhooks são stateless.
• HTTPS preferível: pra dados sensíveis.

Logs e debugging

Cada execução do webhook cria registro em LeadEvent:

Event Type	Significado
webhook_sent	Sucesso (HTTP 2xx). Inclui status + duration_ms.
webhook_failed	Falha. Inclui erro (timeout, 5xx, etc).

Abra o lead, aba Timeline, veja os eventos.

SSRF protection

O sistema bloqueia destinos perigosos:

• localhost, 127.0.0.1, 0.0.0.0
• IPs privados: 10.x, 172.16.x-172.31.x, 192.168.x
• IPs de metadata cloud: 169.254.169.254 (AWS), etc.

Tentativa retorna erro de validação. Pra enviar pra rede interna:

• Use endpoint público que faça proxy.
• Configure VPN ou tunnel se realmente necessário.

Casos práticos

Lead criado → Mailchimp

Gatilho: lead_created
Ação: send_webhook

URL: https://api.mailchimp.com/3.0/lists/abc123/members
Method: POST
Headers:
 Authorization: Bearer apikey123
 Content-Type: application/json
Body (raw):
{
 "email_address": "{{lead.email}}",
 "status": "subscribed",
 "merge_fields": {
 "FNAME": "{{lead.name}}",
 "LNAME": ""
 },
 "tags": "{{lead.tags}}"
}

Lead ganho → ERP

Gatilho: lead_won
Ação: send_webhook

URL: https://erp.empresa.com/api/orders
Method: POST
Headers:
 X-API-Key: chave_secreta_erp
Body (builder):
 customer_name → lead.name
 customer_email → lead.email
 amount → lead.value
 source → literal "syncro-crm"
 closed_at → system.now_iso

Tag aplicada → Slack

Gatilho: lead_created (ou outro com filtro de tag)
Ação: send_webhook

URL: https://hooks.slack.com/services/T00/B00/XXX
Method: POST
Body (raw):
{
 "text": "🎯 Novo lead {{lead.name}} de {{lead.company}} recebido! Valor estimado: R$ {{lead.value}}.",
 "channel": "#vendas",
 "username": "Syncro"
}

Notification customizada

Gatilho: lead_stage_changed (etapa "Aguardando pagamento")
Ação: send_webhook

URL: https://api.empresa.com/notify
Method: POST
Body (raw):
{
 "user_id": "{{lead.assigned_user_id}}",
 "title": "Pagamento pendente",
 "message": "Lead {{lead.name}} aguarda pagamento de R$ {{lead.value}}",
 "lead_id": "{{lead.id}}"
}

Integração com plataformas no-code

O Syncro funciona perfeitamente com:

Zapier

1. Crie um Zap com trigger "Webhooks by Zapier" (catch hook).
2. Cole a URL do hook no Syncro.
3. Após disparar 1x, Zapier captura schema do payload.
4. Configure ações no Zapier.

Make.com (ex-Integromat)

1. Crie um Scenario com módulo "Webhooks → Custom webhook".
2. Cole URL no Syncro.
3. Configure resto do flow no Make.

n8n

1. Crie workflow com nó "Webhook".
2. Cole URL no Syncro.
3. Conecte com outros nós.

Boas práticas

1. Use HTTPS

Sempre. Não envie dados sensíveis em HTTP plain.

2. Autenticação no header

Tokens em header (Authorization), não na URL.

3. Body conciso

Não envie tudo do lead — só o que o sistema externo precisa. Reduz overhead.

4. Idempotência no destino

Sistema externo deve não duplicar se receber mesmo webhook 2x (ex: por retry). Use IDs únicos.

5. Monitor de falhas

Verifique periodicamente os eventos webhook_failed na timeline. Webhook quebrado por dias sem você notar = dados não sincronizados.

6. Versione seu endpoint

Se você muda formato esperado pelo sistema externo, mantém endpoint v1 antigo + cria v2 novo. Atualiza Syncro pro v2 com calma.

Limitações conhecidas

• Sem assinatura HMAC dos webhooks de saída do Syncro (em roadmap pra adicionar segurança).
• Sem batching — cada automação dispara webhook separado (não acumula múltiplos).
• Sem callback success — Syncro envia e "esquece" (one-way).
• Sem GET com query params automáticos — você teria que adicionar query manualmente na URL.

Erros comuns

"Webhook timeout"

• URL externa demora >15s. Otimize o endpoint receptor.

"HTTP 401 Unauthorized"

• Token errado no header.
• Verifique Authorization header.

"HTTP 404 Not Found"

• URL errada.
• Confirme caminho exato.

"SSRF blocked"

• Você usou IP privado / interno.
• Use URL pública.

"Webhook não dispara"

• Confirme que automação está ativa.
• Confirme que gatilho disparou (verificar via outras ações da automação).

Próximos passos

• Pra outras ações, veja Ações de mensagem/mover/tarefa.
• Pra histórico, veja Histórico de execuções.

Artigos relacionados

• Criar automação
• Histórico de execuções
• API e webhooks