Webhooks (gerenciamento)

Webhooks (gerenciamento)

Crie e gerencie endpoints que recebem os eventos da WaBlast. Rotação de segredo e log de entregas.

Gerencie endpoints que recebem os eventos (entrega, leitura, falha, status de template etc.).

POST /v1/webhooks

Cria um endpoint. Retorna o segredo de assinatura uma única vez.

POST /v1/webhooks 201400401404409429

Body (JSON):

{
  "url": "https://seu-app.com/webhooks/wablast",
  "enabledEvents": ["message.delivered", "message.read", "message.failed"],
  "accountId": "ckv...",
  "description": "Produção"
}
Campo Tipo Obrigatório Regras
url string Sim obrig., 8–2048 chars, https://, não pode ser IP privado/loopback (SSRF)
enabledEvents string[] Sim obrig., ≥ 1 evento do catálogo
accountId string Não opcional; limita a uma conexão. null = todas
description string Não opcional, ≤ 255 chars

Limite: 10 endpoints por usuário → 409 ENDPOINT_LIMIT se exceder.

Resposta 201:

Resposta 201

{
"id": "whe_ckv...",
"url": "https://seu-app.com/webhooks/wablast",
"enabledEvents": ["message.delivered", "message.read", "message.failed"],
"whatsAppAccountId": "ckv...",
"status": "ACTIVE",
"description": "Produção",
"consecutiveFailures": 0,
"lastSuccessAt": null,
"createdAt": "2026-06-22T14:00:00.000Z",
"secret": "whsec_AbC123...="
}

O campo secret (formato whsec_…) é retornado apenas aqui. Guarde com segurança — use-o para verificar a assinatura de cada entrega.

GET /v1/webhooks

Lista endpoints (ordenado por createdAt DESC). Mesmo shape do create, sem secret.

GET /v1/webhooks 200401429

PATCH /v1/webhooks/{id}

Atualiza um endpoint. Body (todos opcionais):

{
  "url": "https://novo.com/hook",
  "enabledEvents": ["message.delivered"],
  "status": "PAUSED",
  "description": "..."
}
PATCH /v1/webhooks/{id} 200400401404429

status aceita ACTIVE | PAUSED (o DISABLED é só do sistema). Reativar (ACTIVE) zera consecutiveFailures e limpa disabledAt.

DELETE /v1/webhooks/{id}

Remove o endpoint.

DELETE /v1/webhooks/{id} 200401404429 
{ "deleted": true }

POST /v1/webhooks/{id}/test

Envia um evento de teste assinado para o endpoint. Timeout 5s; 3xx conta como falha; não cria registro de delivery nem faz retry.

POST /v1/webhooks/{id}/test 200401404429

Payload enviado:

{
  "id": "evt_test_<endpointId>",
  "type": "endpoint.test",
  "api_version": "2026-06-01",
  "created_at": "2026-06-22T14:00:00.000Z",
  "data": { "message": "Evento de teste do WaBlast — sua assinatura está correta." }
}

Resposta 200:

{ "delivered": true, "status_code": 200, "error": null }

POST /v1/webhooks/{id}/rotate-secret

Gera um novo segredo e invalida o antigo imediatamente (hard cutover, sem período de graça).

POST /v1/webhooks/{id}/rotate-secret 201401404429

Resposta 201:

{ "id": "whe_ckv...", "secret": "whsec_NovoSegredo...=" }

Após rotacionar, todas as entregas pendentes já assinadas com o segredo antigo falharão a verificação. Faça cutover coordenado: já tenha o novo segredo carregado antes de rotacionar.

GET /v1/webhooks/{id}/deliveries

Log de entregas (paginado por cursor/keyset).

GET /v1/webhooks/{id}/deliveries 200401404429

Query:

Campo Tipo Obrigatório Regras
limit int Não 1–100, default 50
cursor string Não ID da última delivery da página anterior
status enum Não PENDING | DELIVERING | SUCCESS | FAILED | DEAD

Resposta 200:

Resposta 200

{
"deliveries": [
  {
    "id": "whd_ckv...",
    "event_type": "message.delivered",
    "status": "SUCCESS",
    "attempts": 1,
    "last_response_code": 200,
    "last_error": null,
    "delivered_at": "2026-06-22T14:05:00.000Z",
    "created_at": "2026-06-22T14:04:59.000Z"
  }
],
"has_more": false,
"next_cursor": null
}

Ordenado por createdAt DESC, id DESC. Quando has_more=true, passe next_cursor como cursor.

Pular para o conteúdo