API — Webhooks (outbound) e payloads de automação

Receba eventos do CRM em tempo real: cadastro e gestão de webhooks, lista de eventos, verificação de assinatura HMAC SHA-256, auto-desativação por falhas e payload completo das automações.

API — Webhooks (outbound)

Webhooks notificam um endpoint externo (HTTPS) sempre que um evento ocorre no CRM. Base de gestão: /api/v1/webhooks.

Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.
Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.

Endpoints

MétodoPathDescrição
GET/webhooksListar webhooks (sem paginação)
POST/webhooksCriar webhook (retorna o secret)
GET/webhooks/{id}Detalhes (inclui secret)
PUT/webhooks/{id}Atualizar
DELETE/webhooks/{id}Excluir
POST/webhooks/{id}/testDisparar um evento de teste

Eventos disponíveis

Use os identificadores abaixo no array events, ou "*" para escutar todos:

  • contact.created, contact.updated, contact.deleted
  • conversation.created, conversation.updated
  • message.received, message.sent
  • invoice.created, invoice.updated, invoice.paid, invoice.overdue, invoice.cancelled
  • product.created, product.updated, product.deleted

POST /webhooks — criar

CampoTipoRegras
urlurlobrigatório, máx 500, HTTPS recomendado
eventsarrayobrigatório, mín 1; cada item deve ser um evento válido ou *
is_activebooleanpadrão true
POST /api/v1/webhooks
{
  "url": "https://meusite.com/webhook",
  "events": ["message.received", "contact.created"]
}

A resposta inclui o secret gerado — guarde-o, é usado para validar a assinatura. Eventos inválidos no array geram 422.

Payload entregue

{
  "event": "message.received",
  "timestamp": "2026-03-15T10:30:00-03:00",
  "data": {
    "id": 12345,
    "conversation_id": 678,
    "contact_id": 432,
    "direction": "incoming",
    "type": "text",
    "content": "Olá, preciso de ajuda!",
    "status": "delivered",
    "created_at": "2026-03-15T10:30:00-03:00"
  }
}

Dica: use o conversation_id do payload para responder direto via POST /api/v1/messages/send — não é preciso extrair telefone nem informar channel_id.

Verificação de assinatura (HMAC SHA-256)

Cada entrega inclui o header X-Webhook-Signature com o HMAC SHA-256 do corpo bruto, usando o secret do webhook. Sempre valide antes de processar:

$signature = hash_hmac('sha256', $requestBody, $webhookSecret);
if (!hash_equals($signature, $request->header('X-Webhook-Signature'))) {
    abort(401, 'Invalid signature');
}

Auto-desativação

Após 50 falhas consecutivas de entrega, o webhook é desativado automaticamente. Os campos failure_count e last_triggered_at ajudam a monitorar. Para reativar, faça PUT /webhooks/{id} com {"is_active": true}.

Use POST /webhooks/{id}/test para validar a recepção do seu endpoint sem esperar um evento real.


Payload completo de automações

Quando uma Automação usa a ação "Chamar Webhook" com payload completo ativado, o CRM envia um objeto estruturado e rico em contexto — diferente do payload enxuto dos webhooks de API acima. Exemplo para o trigger chat_new_message:

{
  "event": { "automationid": 3, "automationname": "AtendimentoWhatsApp", "triggertype": "chatnewmessage", "timestamp": "...", "tenantid": 1 },
  "entity": { "type": "ChatMessage", "id": 1001, "data": { "content": "...", "type": "text", "direction": "incoming", "remotejid": "5511988880001", "createdat": "..." } },
  "conversation": { "id": 200, "contact_id": 10, "remotejid": "5511988880001", "status": "open", "channelname": "Suporte" },
  "contact": {
    "id": 10, "name": "Carlos Oliveira", "email": "...", "phone": "...", "type": "customer",
    "deals": [ { "id": 5, "title": "Contrato Mensal", "value": 500.00, "status": "open", "pipeline": "Comercial", "stage": "Negociação" } ],
    "recent_invoices": [ { "id": 20, "number": "FAT-00020", "total": 150.00, "status": "paid", "due_date": "...", "paid_at": "..." } ]
  }
}
  • Se a conversa não tiver contato vinculado, o sistema tenta localizá-lo pelo remotejid; não achando, o bloco contact é omitido.
  • Quando há contato, o payload já inclui os 3 últimos negócios e as 3 últimas faturas — evita chamadas extras à API.
  • Dica n8n: se conversation.contact_id for nulo, use GET /api/v1/contacts/by-phone?phone={{ remotejid }}.

Outros triggers com payload completo: chat_new_conversation, chat_new_message, proposal_created/sent/accepted, invoice_created/paid/overdue, deal_created/won/lost, contact_created/updated, support_ticket_created, contract_created/signed.

api webhooks eventos hmac automação n8n integração

Este artigo foi útil?