Eventos dos Webhooks

Na API você pergunta; no webhook a Notifique avisa. Ideal para marcar entrega, medir cliques ou remover device com subscription inválida, sem polling.

Em poucas palavras

Toda entrega é um POST application/json para a URL cadastrada.
Eventos push.* são só push, WhatsApp usa message.*, SMS usa sms.*.
instanceId vem vazio (push não usa instância de canal).
Ative só os eventos que sua integração usa.
Responda 2xx rápido; processamento pesado vai para fila no seu lado.

Configuração geral: Webhooks. Segurança (assinatura HMAC): Segurança de webhooks.

Como vem o POST

{
  "event": "push.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "pushId": "clxx456...",
    "deviceId": "clxx789...",
    "appId": "clxxabc...",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

Campo	Descrição
`event`	Nome do evento (ex.: `push.delivered`)
`workspaceId`	ID do workspace
`instanceId`	Sempre vazio no push
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos do envio (`pushId`, `deviceId`, `appId`, `status`, etc.)

Headers: X-Notifique-Signature, X-Notifique-Timestamp, X-Workspace-Id, X-Webhook-Event.

O que seu servidor deve responder

Resposta	Efeito
2xx em até ~10s	Evento entregue; sai da fila
4xx / 5xx / timeout	Retentativa automática (5 min, 30 min, 2 h)

Processamento demorado? Responda 200 logo e processe em background.

Referência por evento

Evento	Quando dispara	O que fazer com isso
`push.sent`	Push aceito e enviado ao provedor	Marcar como enviado
`push.delivered`	Dispositivo confirmou entrega	Métricas de entrega
`push.clicked`	Usuário abriu a notificação	Deep link, conversão
`push.failed`	Subscription inválida ou erro	Remover ou atualizar device
`push.cancelled`	Agendamento cancelado antes do envio	Atualizar fila

Payload de cada evento

push.sent

{
  "event": "push.sent",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:29:00.000Z",
  "data": {
    "pushId": "clxx456...",
    "deviceId": "clxx789...",
    "appId": "clxxabc...",
    "status": "SENT",
    "title": "Olá!",
    "sentAt": "2025-02-10T14:29:00.000Z"
  }
}

push.delivered

Disparado quando o service worker ou cliente reporta entrega.

{
  "event": "push.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "pushId": "clxx456...",
    "deviceId": "clxx789...",
    "appId": "clxxabc...",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

push.clicked

{
  "event": "push.clicked",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:35:00.000Z",
  "data": {
    "pushId": "clxx456...",
    "deviceId": "clxx789...",
    "appId": "clxxabc...",
    "status": "CLICKED",
    "clickedAt": "2025-02-10T14:35:00.000Z",
    "url": "https://seusite.com/notificacoes"
  }
}

push.failed

Boa prática: desativar ou remover o deviceId ao receber subscription inválida.

{
  "event": "push.failed",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:29:30.000Z",
  "data": {
    "pushId": "clxx456...",
    "deviceId": "clxx789...",
    "appId": "clxxabc...",
    "status": "FAILED",
    "failedAt": "2025-02-10T14:29:30.000Z",
    "errorMessage": "subscription_expired"
  }
}

push.cancelled

{
  "event": "push.cancelled",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T12:00:00.000Z",
  "data": {
    "pushId": "clxx456...",
    "deviceId": "clxx789...",
    "appId": "clxxabc...",
    "status": "CANCELLED"
  }
}

Próximos passos

Quick Start: app → dispositivo → envio
Introdução: ciclo de status
Escopos: permissões da chave
Webhooks (guia geral)

​Em poucas palavras

​Como vem o POST

​O que seu servidor deve responder

​Referência por evento

​Payload de cada evento

​Próximos passos

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Referência por evento

Payload de cada evento

Próximos passos