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.

Endpoints
| Método | Path | Descrição |
|---|---|---|
| GET | /webhooks | Listar webhooks (sem paginação) |
| POST | /webhooks | Criar webhook (retorna o secret) |
| GET | /webhooks/{id} | Detalhes (inclui secret) |
| PUT | /webhooks/{id} | Atualizar |
| DELETE | /webhooks/{id} | Excluir |
| POST | /webhooks/{id}/test | Disparar um evento de teste |
Eventos disponíveis
Use os identificadores abaixo no array events, ou "*" para escutar todos:
contact.created,contact.updated,contact.deletedconversation.created,conversation.updatedmessage.received,message.sentinvoice.created,invoice.updated,invoice.paid,invoice.overdue,invoice.cancelledproduct.created,product.updated,product.deleted
POST /webhooks — criar
| Campo | Tipo | Regras |
|---|---|---|
| url | url | obrigatório, máx 500, HTTPS recomendado |
| events | array | obrigatório, mín 1; cada item deve ser um evento válido ou * |
| is_active | boolean | padrã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 blococontacté 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_idfor nulo, useGET /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.