Guia Completo: Webhooks de Entrada e Saída na Marketek

Integrar a Marketek com sistemas externos é essencial para quem busca automação de ponta a ponta. Os webhooks são o mecanismo mais direto e eficiente para fazer dois sistemas conversarem em tempo real, sem necessidade de consultas periódicas ou importações manuais.

Neste guia, você vai entender o que são webhooks, como funcionam os de entrada e saída na Marketek, como configurá-los na prática e quais cuidados tomar para garantir segurança e confiabilidade nas suas integrações.

O Que São Webhooks e Por Que Usá-los

Webhooks são chamadas HTTP automáticas disparadas quando um evento específico acontece em um sistema. Diferente de uma API tradicional, onde você precisa fazer requisições periodicamente para verificar se algo mudou, o webhook envia os dados instantaneamente assim que o evento ocorre.

Pense assim: em vez de você ligar para a loja toda hora perguntando se o pedido chegou, a loja te avisa automaticamente quando ele chega. Essa é a lógica do webhook.

Vantagens dos webhooks

• Tempo real: dados transmitidos no instante em que o evento acontece
• Eficiência: elimina requisições desnecessárias e reduz carga nos servidores
• Simplicidade: configuração mais direta que integrações complexas via API
• Flexibilidade: funciona com praticamente qualquer sistema que aceite HTTP

Na Marketek, existem dois tipos principais: webhooks de entrada (inbound) e webhooks de saída (outbound).

Webhooks de Entrada (Inbound)

Os webhooks de entrada permitem que sistemas externos enviem dados para a Marketek. Você cria uma URL de recebimento dentro da plataforma, e qualquer sistema pode fazer um POST para essa URL com os dados que você precisa.

Configurando um Webhook de Entrada

1. Acesse Configurações > Integrações > Webhooks
2. Clique em Criar Webhook de Entrada
3. Dê um nome descritivo ao webhook (ex.: “Formulário Site Externo”)
4. A Marketek gerará uma URL única — copie essa URL
5. Configure o sistema externo para enviar dados via POST para essa URL
6. Defina o mapeamento de campos na aba Mapeamento

Formato do Payload (JSON)

O payload enviado deve estar no formato JSON. Exemplo de estrutura aceita:

{
  "nome": "Mária Silva",
  "email": "mária@exemplo.com",
  "telefone": "+5511999998888",
  "origem": "landing-page-verao"
}

A Marketek aceita payloads com campos personalizados. Basta mapear cada chave do JSON para o campo correspondente no cadastro do contato.

Casos de uso comuns

• Receber leads de formulários hospedados fora da Marketek
• Sincronizar dados de um ERP ou sistema de gestão
• Importar eventos de compra de uma plataforma de e-commerce
• Receber notificações de pagamento de gateways

Webhooks de Saída (Outbound)

Os webhooks de saída fazem o caminho inverso: a Marketek envia dados para um sistema externo quando um evento específico acontece dentro da plataforma.

Configurando um Webhook de Saída

1. Acesse Configurações > Integrações > Webhooks
2. Clique em Criar Webhook de Saída
3. Insira a URL de destino do sistema que receberá os dados
4. Selecione o evento gatilho (ex.: novo contato criado, oportunidade movida, tag adicionada)
5. Escolha quais campos devem ser incluídos no payload
6. Salve e ative o webhook

Eventos Disponíveis para Gatilho

Você pode criar múltiplos webhooks de saída para diferentes eventos, cada um apontando para URLs distintas.

Autenticação e Segurança

Proteger seus webhooks é fundamental para evitar que dados sensíveis sejam interceptados ou que requisições falsas sejam processadas.

Boas práticas de segurança

• Use HTTPS: sempre configure URLs com certificado SSL para criptografar os dados em trânsito
• Token de autenticação: adicione um header personalizado (ex.: X-Webhook-Token) com um valor secreto e valide no servidor de destino
• Validação de IP: se possível, restrinja o recebimento apenas aos IPs da Marketek
• Verificação de payload: valide a estrutura dos dados recebidos antes de processá-los
• Timeout configurado: defina um tempo limite de resposta para evitar conexões pendentes

Na Marketek, você pode configurar headers personalizados em Configurações > Integrações > Webhooks > Editar > Headers de Autenticação. Adicione o nome do header e o valor secreto que o servidor de destino deve validar.

Testando Seus Webhooks

Antes de colocar um webhook em produção, é essencial testá-lo para garantir que os dados estão sendo enviados e recebidos corretamente.

Ferramentas de teste recomendadas

• webhook.site: gera uma URL temporária que captura e exibe qualquer requisição recebida — ideal para testar webhooks de saída
• Postman: permite enviar requisições POST manuais para testar webhooks de entrada
• curl: ferramenta de linha de comando para testes rápidos

Exemplo de teste com curl

curl -X POST https://sua-url-webhook.marketek.digital/webhook/abc123 
  -H "Content-Type: application/json" 
  -d '{"nome":"Teste","email":"teste@exemplo.com"}'

Checklist de validação

• [ ] URL correta e acessível
• [ ] Método HTTP é POST
• [ ] Content-Type é application/json
• [ ] Payload contém todos os campos necessários
• [ ] Headers de autenticação estão configurados
• [ ] Mapeamento de campos está correto
• [ ] Workflow associado está ativo (para webhooks de entrada)

Casos de Uso Práticos

Integração com sistema de gestão financeira

Configure um webhook de saída para enviar dados do contato quando uma oportunidade for marcada como “ganha”. O sistema financeiro recebe os dados e cria automaticamente uma fatura.

Sincronização com ferramenta de suporte

Quando um contato preenche um formulário de suporte na Marketek, um webhook de saída envia os dados para o sistema de tickets, que cria um chamado automaticamente.

Recebimento de leads de marketplace

Plataformas de marketplace enviam dados de leads interessados via webhook de entrada. A Marketek recebe, cria o contato e dispara um workflow de follow-up automático.

Notificações personalizadas

Configure webhooks de saída para enviar dados a um serviço de notificação customizado, alertando sua equipe via Slack, Discord ou qualquer outro canal quando eventos importantes acontecem.

Artigos Relacionados:
– Como Receber Dados de Formulários Externos via Webhook
– Webhook Não Funciona? Diagnóstico Passo a Passo