Webhooks (Server)

Esta página descreve o que sua aplicação recebe nos webhooks configurados quando a Sendeasy processa eventos de canal e mensagem.

Escopos: geral e por canal

Webhooks têm dois escopos possíveis:

• Geral: recebe eventos de todos os canais da empresa. Pense nele como o webhook "global" da conta.
• Por canal específico: recebe eventos apenas do canal ao qual está amarrado.

Os dois escopos coexistem. Para cada evento, a Sendeasy dispara a união: todos os webhooks gerais ativos da empresa mais o(s) webhook(s) por canal específico daquele canal. Configure quantos webhooks quiser de cada escopo.

Exemplo: a empresa tem 2 instâncias de WhatsApp e 1 caixa de Email. Você pode configurar:

• 1 webhook na URL A → recebe só eventos do WhatsApp Vendas.
• 1 webhook na URL B → recebe só eventos do WhatsApp Suporte.
• 1 webhook na URL C → recebe só eventos do Email Suporte.

A configuração é feita em Configurações → Integrações.

Fluxo resumido

1. A Sendeasy processa um evento de canal/mensagem.
2. O payload é normalizado conforme o contrato público.
3. A Sendeasy busca todos os webhooks enabled=true amarrados ao canal de origem do evento.
4. Para cada webhook encontrado, faz um POST na URL configurada com o payload no body. Se houver bearer token configurado, ele é enviado no header Authorization.

Payload base

{
  "event": "messages.upsert",
  "channel": "whatsapp",
  "data": {},
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Eventos por canal

WhatsApp (channel: "whatsapp" ou "waba")

connection.update

{ "state": "open" }

Valores comuns: open, close.

messages.upsert / messages.set / send.message

{
  "key": {
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false,
    "id": "3EB0XXXXXX"
  },
  "message": { "conversation": "Olá, preciso de ajuda" },
  "messageTimestamp": "1634567890",
  "pushName": "Cliente"
}

messages.update

{ "keyId": "3EB0XXXXXX", "fromMe": true, "status": 3 }

status: 1 (sent), 2 (delivered), 3 (read).

messages.delete

{ "id": "3EB0XXXXXX", "fromMe": false, "remoteJid": "5511999999999@s.whatsapp.net" }

call

{ "id": "CALL_ID_123", "from": "5511999999999@s.whatsapp.net", "status": "reject" }

status: reject, terminate.

WABA — messaging e message_status

{
  "event": "message_status",
  "channel": "whatsapp",
  "data": { "messageId": "wamid.HBg...", "status": "read", "timestamp": "1713800010" },
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Email (channel: "email")

Disparado quando a caixa amarrada ao webhook recebe um e-mail.

{
  "event": "messaging",
  "channel": "email",
  "channelId": 7,
  "data": {
    "email": {
      "direction": "inbound",
      "mailbox": "suporte@empresa.com",
      "from": { "email": "cliente@dominio.com", "name": "Cliente" },
      "to": ["suporte@empresa.com"],
      "subject": "Dúvida sobre o pedido #1234",
      "text": "Olá, gostaria de saber...",
      "html": "<p>...</p>",
      "messageId": "<abc@dominio.com>",
      "receivedAt": "2026-04-28T13:45:00.000Z"
    }
  }
}

SMS (channel: "sms")

Disparado quando o número amarrado ao webhook recebe um SMS.

{
  "event": "messaging",
  "channel": "sms",
  "channelId": 15,
  "data": {
    "sms": {
      "direction": "inbound",
      "from": "+5511999999999",
      "body": "Confirmar agendamento",
      "providerPayload": { "...": "raw provider data" }
    }
  }
}

Boas práticas de consumo

1. Trate o processamento como assíncrono e implemente retry com backoff.
2. Use idempotência por event + identificadores (key.id, keyId, data.email.messageId, etc.).
3. Armazene o payload bruto para troubleshooting.
4. Valide o header Authorization quando configurado no webhook.
5. Configure timeouts curtos (≤ 5s) — se a Sendeasy não receber resposta em 5s, o webhook é considerado falho e o evento é descartado (não há retry automático).

Onde gerenciar

A configuração e ativação de webhooks é feita em Configurações → Integrações na plataforma.