Webhooks

Endereços que recebem os eventos da instância, com histórico de entregas.

Basehttps://app.onzap.io/v1/instances/{instanceId}AuthX-Instance-Token: SEU_TOKEN

Listar webhooks

GET/v1/instances/{instanceId}/webhooks

API OnZapAPI oficial

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Webhooks da instância e eventos disponíveis

{
  "data": [
    {
      "consecutiveFailures": 0,
      "createdAt": "2026-09-30T14:05:00Z",
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "disabledAt": "2026-09-30T14:05:00Z",
      "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
      "enabled": false,
      "events": [
        "message.any"
      ],
      "failingSince": "2026-09-30T14:05:00Z",
      "headers": {},
      "id": "whk_01jabcdefghjkmnpqrstvwxy",
      "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
      "instanceName": "Loja Centro",
      "lastDeliveryAt": "2026-09-30T14:05:00Z",
      "lastSuccess": false,
      "responseTime": {
        "medianMs": 0,
        "p95Ms": 0,
        "samples": 0
      },
      "secret": "8f14e45fceea167a5a36dedd4bea2543",
      "updatedAt": "2026-09-30T14:05:00Z",
      "url": "https://exemplo.com.br/arquivos/pedido.jpg"
    }
  ],
  "events": [
    "message.any"
  ]
}

Criar webhook

POST/v1/instances/{instanceId}/webhooks

API OnZapAPI oficial

Até 5 por instância. O secret gerado vem na resposta: use-o para conferir X-OnZap-Signature.

Corpo (JSON)

eventsarray de stringobrigatório

Eventos a receber (* = todos). Lista completa na seção Webhooks.

urlstringobrigatório

Endereço HTTPS público.

descriptionstringopcional

Descrição livre, para você identificar o webhook.

enabledbooleanopcional

Ativa ou desativa sem apagar.

headersobjectopcional

Headers extras (não podem sobrescrever Content-Type, User-Agent nem os X-OnZap-*).

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "message",
      "message.ack"
    ],
    "url": "https://seu-sistema.com.br/webhooks/whatsapp"
  }'

Resposta

Webhook criado

{
  "consecutiveFailures": 0,
  "createdAt": "2026-09-30T14:05:00Z",
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "disabledAt": "2026-09-30T14:05:00Z",
  "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
  "enabled": false,
  "events": [
    "message.any"
  ],
  "failingSince": "2026-09-30T14:05:00Z",
  "headers": {},
  "id": "whk_01jabcdefghjkmnpqrstvwxy",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "instanceName": "Loja Centro",
  "lastDeliveryAt": "2026-09-30T14:05:00Z",
  "lastSuccess": false,
  "responseTime": {
    "medianMs": 0,
    "p95Ms": 0,
    "samples": 0
  },
  "secret": "8f14e45fceea167a5a36dedd4bea2543",
  "updatedAt": "2026-09-30T14:05:00Z",
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}

Consultar webhook

GET/v1/instances/{instanceId}/webhooks/{webhookId}

API OnZapAPI oficial

Parâmetros do caminho

webhookIdstringobrigatório

ID do webhook.

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Webhook

{
  "consecutiveFailures": 0,
  "createdAt": "2026-09-30T14:05:00Z",
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "disabledAt": "2026-09-30T14:05:00Z",
  "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
  "enabled": false,
  "events": [
    "message.any"
  ],
  "failingSince": "2026-09-30T14:05:00Z",
  "headers": {},
  "id": "whk_01jabcdefghjkmnpqrstvwxy",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "instanceName": "Loja Centro",
  "lastDeliveryAt": "2026-09-30T14:05:00Z",
  "lastSuccess": false,
  "responseTime": {
    "medianMs": 0,
    "p95Ms": 0,
    "samples": 0
  },
  "secret": "8f14e45fceea167a5a36dedd4bea2543",
  "updatedAt": "2026-09-30T14:05:00Z",
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}

Alterar webhook

PATCH/v1/instances/{instanceId}/webhooks/{webhookId}

API OnZapAPI oficial

Só os campos enviados mudam. Reativar (enabled: true) zera o contador de falhas.

Parâmetros do caminho

webhookIdstringobrigatório

ID do webhook.

Corpo (JSON)

descriptionstringopcional

Descrição livre, para você identificar o webhook.

enabledbooleanopcional

Ativa ou desativa sem apagar.

eventsarray de stringopcional

Eventos a receber (* = todos). Lista completa na seção Webhooks.

headersobjectopcional

Headers extras (não podem sobrescrever Content-Type, User-Agent nem os X-OnZap-*).

urlstringopcional

Endereço HTTPS público.

Requisição

curl -X PATCH "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta

Webhook atualizado

{
  "consecutiveFailures": 0,
  "createdAt": "2026-09-30T14:05:00Z",
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "disabledAt": "2026-09-30T14:05:00Z",
  "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
  "enabled": false,
  "events": [
    "message.any"
  ],
  "failingSince": "2026-09-30T14:05:00Z",
  "headers": {},
  "id": "whk_01jabcdefghjkmnpqrstvwxy",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "instanceName": "Loja Centro",
  "lastDeliveryAt": "2026-09-30T14:05:00Z",
  "lastSuccess": false,
  "responseTime": {
    "medianMs": 0,
    "p95Ms": 0,
    "samples": 0
  },
  "secret": "8f14e45fceea167a5a36dedd4bea2543",
  "updatedAt": "2026-09-30T14:05:00Z",
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}

Excluir webhook

DELETE/v1/instances/{instanceId}/webhooks/{webhookId}

API OnZapAPI oficial

Parâmetros do caminho

webhookIdstringobrigatório

ID do webhook.

Requisição

curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Excluído

Enviar evento de teste

POST/v1/instances/{instanceId}/webhooks/{webhookId}/test

API OnZapAPI oficial

Entrega um webhook.test só para este webhook (mesmo desativado). Acompanhe em /deliveries.

Parâmetros do caminho

webhookIdstringobrigatório

ID do webhook.

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/test" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Teste enfileirado

{
  "event": "webhook.test",
  "eventId": "evt_01jabcdefghjkmnpqrstvwxyz0"
}

Gerar novo segredo

POST/v1/instances/{instanceId}/webhooks/{webhookId}/rotate-secret

API OnZapAPI oficial

O segredo anterior deixa de valer imediatamente.

Parâmetros do caminho

webhookIdstringobrigatório

ID do webhook.

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/rotate-secret" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Webhook com o novo segredo

{
  "consecutiveFailures": 0,
  "createdAt": "2026-09-30T14:05:00Z",
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "disabledAt": "2026-09-30T14:05:00Z",
  "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
  "enabled": false,
  "events": [
    "message.any"
  ],
  "failingSince": "2026-09-30T14:05:00Z",
  "headers": {},
  "id": "whk_01jabcdefghjkmnpqrstvwxy",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "instanceName": "Loja Centro",
  "lastDeliveryAt": "2026-09-30T14:05:00Z",
  "lastSuccess": false,
  "responseTime": {
    "medianMs": 0,
    "p95Ms": 0,
    "samples": 0
  },
  "secret": "8f14e45fceea167a5a36dedd4bea2543",
  "updatedAt": "2026-09-30T14:05:00Z",
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}

Histórico de entregas

GET/v1/instances/{instanceId}/webhooks/{webhookId}/deliveries

API OnZapAPI oficial

Entregas dos últimos 30 dias, das mais novas para as mais antigas.

Parâmetros do caminho

webhookIdstringobrigatório

ID do webhook.

Parâmetros de query

statusstringopcional

Filtra pelo resultado.

limitintegeropcional

Itens por página (padrão 50, máximo 100).

cursorstringopcional

Continuação: o nextCursor da página anterior.

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/deliveries" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Página de entregas

{
  "data": [
    {
      "attempts": 1,
      "createdAt": "2026-09-30T14:05:00Z",
      "durationMs": 0,
      "error": "número sem WhatsApp",
      "event": "message.any",
      "eventId": "evt_01jabcdefghjkmnpqrstvwxyz0",
      "id": "dlv_01jabcdefghjkmnpqrstvwxy",
      "nextAttemptAt": "2026-09-30T14:05:00Z",
      "response": "{\"id\":\"[email protected]_3EB0C0A1B2C3D4E5F6\"}",
      "status": "success",
      "statusCode": 0,
      "updatedAt": "2026-09-30T14:05:00Z"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjUwfQ"
}

Consultar entrega

GET/v1/instances/{instanceId}/webhooks/{webhookId}/deliveries/{deliveryId}

API OnZapAPI oficial

Inclui o corpo exato enviado (payload).

Parâmetros do caminho

webhookIdstringobrigatório

ID do webhook.

deliveryIdstringobrigatório

ID da entrega.

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/deliveries/dlv_01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Entrega

{
  "attempts": 1,
  "createdAt": "2026-09-30T14:05:00Z",
  "durationMs": 0,
  "error": "número sem WhatsApp",
  "event": "message.any",
  "eventId": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "id": "dlv_01jabcdefghjkmnpqrstvwxy",
  "nextAttemptAt": "2026-09-30T14:05:00Z",
  "response": "{\"id\":\"[email protected]_3EB0C0A1B2C3D4E5F6\"}",
  "status": "success",
  "statusCode": 0,
  "updatedAt": "2026-09-30T14:05:00Z"
}

Reenviar entrega

POST/v1/instances/{instanceId}/webhooks/{webhookId}/deliveries/{deliveryId}/retry

API OnZapAPI oficial

Cria uma nova entrega do mesmo evento (o evento precisa ter menos de 7 dias).

Parâmetros do caminho

webhookIdstringobrigatório

ID do webhook.

deliveryIdstringobrigatório

ID da entrega.

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/deliveries/dlv_01jabcdefghjkmnpqrstvwxyz0/retry" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Reenvio enfileirado

{
  "deliveryId": "dlv_01jabcdefghjkmnpqrstvwxy"
}