Skip to main content

​
Pré-requisitos

  • API Key com escopos: webhooks:read (listar entregas e consultar detalhe) e/ou webhooks:manage (criar, editar, deletar e reenviar entregas).
  • Envie a API Key em toda requisição:
    • Header: Authorization: Bearer sk_live_xxxxx
    • ou Header: x-api-key: sk_live_xxxxx

​
1. Listar webhooks

Lista os webhooks configurados no workspace. Opcionalmente filtre por evento. Request 
GET /v1/webhooks?page=1&limit=20&event=message.sent
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "data": [
    {
      "id": "clxx...",
      "workspaceId": "clyy...",
      "name": "Meu webhook",
      "url": "https://api.seudominio.com/receive",
      "events": ["message.sent", "message.delivered"],
      "instanceIds": [],
      "enabled": true,
      "createdAt": "2025-02-01T10:00:00.000Z",
      "updatedAt": "2025-02-20T12:00:00.000Z"
    }
  ],
  "pagination": { "total": 2, "page": 1, "limit": 20, "totalPages": 1 }
}
O secret não é retornado na listagem; use GET /v1/webhooks/:id para obter o secret (validação HMAC).

​
2. Criar webhook

Cria um novo webhook. A url é validada (formato e acessibilidade em até 3 segundos). Eventos: ex. message.sent, message.delivered, instance.qrcode, instance.connected, sms.sent, email.sent. Request 
POST /v1/webhooks
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu webhook",
  "url": "https://api.seudominio.com/receive",
  "events": ["message.sent", "message.delivered", "instance.qrcode"],
  "instanceIds": []
}
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx...",
    "workspaceId": "clyy...",
    "name": "Meu webhook",
    "url": "https://api.seudominio.com/receive",
    "secret": "whsec_xxxx...",
    "events": ["message.sent", "message.delivered"],
    "instanceIds": [],
    "enabled": true,
    "createdAt": "2025-02-20T12:00:00.000Z",
    "updatedAt": "2025-02-20T12:00:00.000Z"
  }
}
Guarde o secret para validar a assinatura HMAC dos POSTs que o Notifique enviar à sua URL.

​
3. Obter webhook por ID (inclui secret)

Retorna um webhook pelo ID. Inclui o campo secret (usado para assinatura HMAC). Request 
GET /v1/webhooks/:id
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx...",
    "workspaceId": "clyy...",
    "name": "Meu webhook",
    "url": "https://api.seudominio.com/receive",
    "secret": "whsec_xxxx...",
    "events": ["message.sent", "message.delivered"],
    "instanceIds": [],
    "enabled": true,
    "createdAt": "2025-02-01T10:00:00.000Z",
    "updatedAt": "2025-02-20T12:00:00.000Z"
  }
}

​
4. Listar entregas (deliveries)

Lista as tentativas de entrega de eventos às suas URLs. Use para ver se seus endpoints receberam os POSTs e como responderam. Request 
GET /v1/webhooks/deliveries?page=1&limit=20&success=true
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "data": [
    {
      "id": "clxx...",
      "webhookId": "clyy...",
      "messageId": "clzz...",
      "event": "message.sent",
      "payload": { "data": { "messageId": "clzz...", "to": "5511999999999", "status": "SENT" } },
      "statusCode": 200,
      "response": "OK",
      "attempts": 1,
      "success": true,
      "duration": 120,
      "createdAt": "2025-02-20T14:30:01.000Z",
      "webhook": { "name": "Meu webhook", "url": "https://api.seudominio.com/receive" }
    }
  ],
  "pagination": { "total": 50, "page": 1, "limit": 20, "totalPages": 3 }
}

​
5. Obter uma entrega por ID

Retorna o detalhe de uma linha de entrega (útil para inspecionar o payload gravado e o corpo de resposta do seu servidor). Request 
GET /v1/webhooks/deliveries/:id
Authorization: Bearer sk_live_xxxxx
Response (200) — campos principais: payload, statusCode, response, webhook (nome, URL, enabled).

​
6. Reenviar uma entrega manualmente

Equivalente ao botão de reenvio no dashboard: enfileira novamente o mesmo evento para a URL do webhook. Exige webhooks:manage e webhook habilitado (enabled: true). Útil depois de corrigir seu endpoint ou para testes. Request 
POST /v1/webhooks/deliveries/:id/resend
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "message": "Webhook queued for resend"
}
Erros comuns: 404 se o ID não existir no workspace; 400 se o webhook estiver desabilitado; 403 sem escopo webhooks:manage.

​
7. Validar assinatura (HMAC)

No seu endpoint que recebe os POSTs do Notifique:
  • Conteúdo: timestamp + "." + body (body bruto UTF-8).
  • Algoritmo: HMAC-SHA256(secret, conteúdo).
  • Header: X-Notifique-Signature: t=<timestamp>,v1=<hex>; X-Notifique-Timestamp = mesmo timestamp. Rejeite requisições com timestamp fora de uma janela (ex.: 5 minutos).

​
Resumo do fluxo

  1. POST /v1/webhooks com name, url, events (e opcionalmente instanceIds) → criar webhook; guardar secret.
  2. GET /v1/webhooks → listar webhooks; GET /v1/webhooks/:id → obter um (inclui secret).
  3. GET /v1/webhooks/deliveries → conferir entregas; GET /v1/webhooks/deliveries/:id → detalhe de uma entrega; POST /v1/webhooks/deliveries/:id/resend → reenviar manualmente (escopo webhooks:manage).
  4. PUT /v1/webhooks/:id → atualizar webhook; DELETE /v1/webhooks/:id → remover.
  5. No seu servidor: validar assinatura HMAC com o secret em todo POST recebido.