Webhooks

Configure webhooks para receber eventos em tempo real. Cada webhook cadastrado em /u/webhooks responde por um único tipo de evento (ou variantes agregadas).

Configuração

Acesse Webhooks

No painel, vá em /u/webhooks e clique em Adicionar webhook.

Escolha o tipo de evento

Selecione qual evento deve ser enviado — ver tabela abaixo.

Informe a URL de destino

URL HTTPS pública que receberá os eventos via POST.

Segurança

Implemente estas proteções no seu servidor:

Validação HMAC: valide o header X-Signature com o client_token da instância.
Validação de timestamp: rejeite requisições com X-Timestamp antigo (> 5 minutos).
Idempotência: use X-Idempotency-Key para deduplicar entregas.
HTTPS: URLs http:// e IPs privados são bloqueados.

Eventos Disponíveis

`event_type`	Descrição
`message_received`	Nova mensagem recebida do cliente
`message_sent`	Mensagem enviada pela instância
`both`	Mensagens recebidas + enviadas
`contact_created`	Novo contato criado (WhatsApp, API, importação, formulário, widget…)
`contact_updated`	Contato existente teve campos relevantes alterados
`contact_any`	Contatos criados + atualizados

Quando `contact_updated` dispara

Apenas quando um dos seguintes campos muda: name, email, company, job_title, notes, custom_labels, utm_source, utm_medium, utm_campaign, is_favorite, is_archived, is_blocked. Mudanças em last_message_at, photo_url, unread_count e outros campos operacionais não disparam webhook.

Payload de mensagem

{
  "event": "message_received",
  "instance_id": "internal_<uuid>",
  "message": {
    "id": "…",
    "phone": "5511999999999",
    "message_type": "text",
    "content_text": "Olá, preciso de ajuda",
    "timestamp": "2024-01-15T10:30:00Z",
    "from_me": false,
    "sender_name": "João Silva",
    "chat_name": null
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Payload de contato

Mesma estrutura da API /contacts-api/create, acrescida de metadados do evento:

{
  "event": "contact_created",
  "instanceId": "SUA_INSTANCIA",
  "instanceName": "Stegia Comercial",
  "contactId": "uuid-do-contato",
  "phone": "5511999999999",
  "name": "João Silva",
  "email": "joao@email.com",
  "company": "ACME Corp",
  "jobTitle": "Diretor",
  "notes": "Lead vindo do formulário Trabalhe Conosco",
  "tags": ["vip", "lead-quente"],
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "black-friday",
  "customLabels": {
    "contratante": "1346452978",
    "vincular_vaga": "1409608130",
    "segmento": "premium"
  },
  "origin": "form",
  "isFavorite": false,
  "isArchived": false,
  "isBlocked": false,
  "changedKeys": null,
  "createdAt": "2026-07-09T10:30:00Z",
  "updatedAt": "2026-07-09T10:30:00Z",
  "timestamp": "2026-07-09T10:30:00Z"
}

Em contact_updated, changedKeys traz um array com os campos que mudaram, ex.: ["email", "custom_labels"].

customLabels é sempre um objeto JSON ({"chave": "valor"}), igual ao aceito no endpoint /contacts-api/create. Consuma direto em Zapier/Make/n8n via payload.customLabels.contratante.

Headers enviados

Header	Descrição
`X-Client-Token`	Token da instância (mesmo usado na API)
`X-Signature`	HMAC-SHA256 do body assinado com o `client_token`
`X-Signature-Version`	Sempre `v1`
`X-Timestamp`	Timestamp em ms (evita replay)
`X-Idempotency-Key`	Chave única do evento
`X-Event-Type`	Nome do evento (`contact_created`, `message_received`, etc.)

Retry Policy

Se seu servidor retornar erro (status ≥ 500) ou timeout (> 30s), o sistema tenta reenviar até 3 vezes com backoff exponencial (1s → 2s → 4s). Respostas 4xx não são reenviadas.

Retorne 200 o mais rápido possível. Processe a lógica de negócio de forma assíncrona para evitar timeouts.

​Webhooks

​Configuração

​Segurança

​Eventos Disponíveis

​Quando contact_updated dispara

​Payload de mensagem

​Payload de contato

​Headers enviados

​Retry Policy

Webhooks

Configuração

Segurança

Eventos Disponíveis

Quando `contact_updated` dispara

Payload de mensagem

Payload de contato

Headers enviados

Retry Policy