Webhooks - Eventos

A API de Eventos de Webhook lista, detalha e reenvia as entregas feitas aos destinos configurados na sua organização.

Cada item da listagem representa a entrega de um evento a um webhook. O mesmo evento pode aparecer mais de uma vez se foi enviado a vários destinos. O detalhe agrupa essas entregas em deliveries e inclui o payload original e o histórico de tentativas.

Os eventos vêm do mesmo log de entrega usado pelo console. Sem um tenant de webhooks configurado, a listagem devolve vazio.

Propriedades

Name
event_id
Type
string
Description
ID do evento. O mesmo ID pode aparecer em mais de uma linha da listagem, uma por webhook. Use event_id com webhook.id para identificar uma entrega. Use event_id para consultar o detalhe e para reenvio.
Name
topic
Type
string
Description
Tópico do evento, por exemplo traffic-violation.created.
Name
status
Type
string
Description
Status agregado da entrega neste webhook. delivered se alguma tentativa teve sucesso.
Valor Descrição
delivered Pelo menos uma tentativa foi bem-sucedida.
failed Nenhuma tentativa foi bem-sucedida.
Name
time
Type
string
Description
Data e hora do evento em ISO 8601.
Name
attempt_count
Type
number
Description
Número de tentativas de entrega neste webhook.
Name
last_attempt_at
Type
string | null
Description
Data e hora da última tentativa em ISO 8601.
Name
last_status
Type
string | null
Description
Status bruto da última tentativa (success ou failed).
Name
last_code
Type
string | null
Description
Código da última tentativa, em geral o status HTTP da resposta.
Name
last_attempt_number
Type
number | null
Description
Número sequencial da última tentativa.
Name
manual
Type
boolean
Description
Indica se a última tentativa foi um reenvio manual.
Name
eligible_for_retry
Type
boolean
Description
Indica se o destino ainda considera a entrega reenviável (true) ou se o ciclo de retentativas já encerrou (false). Independente de status: um evento delivered pode continuar true, e um failed pode já estar false. Os endpoints de reenvio não usam este campo para aceitar ou recusar o pedido.
Name
webhook
Type
object
Description
Webhook que recebeu esta entrega.
- Name
  id
  Type
  string
  Description
  ID do webhook.
- Name
  url
  Type
  string
  Description
  URL de destino.
Name
payload
Type
object
Description
Presente apenas no detalhe. Corpo original do evento enviado ao webhook.
Name
metadata
Type
object | null
Description
Presente apenas no detalhe. Metadados associados ao evento.
Name
deliveries
Type
array
Description
Presente apenas no detalhe. Uma entrada por webhook, com o histórico de tentativas (status, code, response_body, attempt_number, manual, time).

Valor	Descrição
`delivered`	Pelo menos uma tentativa foi bem-sucedida.
`failed`	Nenhuma tentativa foi bem-sucedida.

GET/v1/webhooks/events

Listar Eventos

Retorna as entregas da organização, da mais recente para a mais antiga.

O campo summary ignora o filtro de status para manter os totais globais de entregues e falhas.

Paginação

Use apenas um dos dois métodos:

Name
pagination[page]
Type
integer
Description
Número da página, começando em 1. Use junto com pagination[size].
Name
pagination[size]
Type
integer
Description
Itens por página, máximo 100. Use junto com pagination[page].
Name
pagination[start]
Type
integer
Description
Offset inicial. Use junto com pagination[limit].
Name
pagination[limit]
Type
integer
Description
Quantidade de itens a retornar, máximo 100. Use junto com pagination[start].

Filtros

Name
filters[webhook_id]
Type
object
Description
Filtra pelo ID do webhook.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor.
Name
filters[status]
Type
object
Description
Filtra pelo status agregado (delivered ou failed).
- Name
  $eq
  Type
  string
  Description
  Igual ao valor. Ex: failed.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor.
Name
filters[topic]
Type
object
Description
Filtra pelo tópico do evento ($eq, $ne).
Name
filters[event_id]
Type
object
Description
Filtra pelo ID do evento ($eq).
Name
filters[time]
Type
object
Description
Filtra pela data do evento. Aceita YYYY-MM-DD ou timestamp ISO 8601.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor.
- Name
  $lt
  Type
  string
  Description
  Menor que o valor.
- Name
  $lte
  Type
  string
  Description
  Menor ou igual ao valor.
- Name
  $gt
  Type
  string
  Description
  Maior que o valor.
- Name
  $gte
  Type
  string
  Description
  Maior ou igual ao valor.

Request

GET

/v1/webhooks/events

curl -G https://api.habilitar.me/v1/webhooks/events \
  -H "x-api-key: {token}" \
  -d "pagination[page]=1" \
  -d "pagination[size]=10"

Response

{
  "data": [
    {
      "event_id": "evt_a056V7R7NmNRjl70",
      "topic": "traffic-violation.created",
      "status": "failed",
      "time": "2026-07-30T18:31:43.720Z",
      "attempt_count": 2,
      "last_attempt_at": "2026-07-30T18:32:10.120Z",
      "last_status": "failed",
      "last_code": "500",
      "last_attempt_number": 2,
      "manual": false,
      "eligible_for_retry": true,
      "webhook": {
        "id": "des_01J8Z3K4N5P6Q7R8S9T0",
        "url": "https://example.com/webhooks"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10,
    "total": 1
  },
  "total": 1,
  "summary": {
    "total": 12,
    "delivered": 10,
    "failed": 2
  }
}

GET/v1/webhooks/events/{eventId}

Detalhar Evento

Retorna o payload, os metadados e o histórico de tentativas de cada webhook que recebeu o evento.

Parâmetros de Rota

Name
eventId
Type
string
Required
obrigatório
Description
ID do evento.

Request

GET

/v1/webhooks/events/{eventId}

curl https://api.habilitar.me/v1/webhooks/events/evt_a056V7R7NmNRjl70 \
  -H "x-api-key: {token}"

Response

{
  "data": {
    "event_id": "evt_a056V7R7NmNRjl70",
    "topic": "traffic-violation.created",
    "status": "failed",
    "time": "2026-07-30T18:31:43.720Z",
    "attempt_count": 2,
    "last_attempt_at": "2026-07-30T18:32:10.120Z",
    "last_status": "failed",
    "last_code": "500",
    "last_attempt_number": 2,
    "manual": false,
    "eligible_for_retry": true,
    "webhook": {
      "id": "des_01J8Z3K4N5P6Q7R8S9T0",
      "url": "https://example.com/webhooks"
    },
    "payload": {
      "type": "traffic-violation.created",
      "data": {
        "id": 1,
        "ait": "AIT123456789"
      }
    },
    "metadata": {
      "source": "api"
    },
    "deliveries": [
      {
        "webhook": {
          "id": "des_01J8Z3K4N5P6Q7R8S9T0",
          "url": "https://example.com/webhooks"
        },
        "status": "failed",
        "eligible_for_retry": true,
        "attempt_count": 2,
        "last_attempt_at": "2026-07-30T18:32:10.120Z",
        "last_status": "failed",
        "last_code": "500",
        "last_attempt_number": 2,
        "manual": false,
        "attempts": [
          {
            "id": "att_2",
            "status": "failed",
            "code": "500",
            "response_body": "{\"error\":\"timeout\"}",
            "attempt_number": 2,
            "manual": false,
            "time": "2026-07-30T18:32:10.120Z"
          },
          {
            "id": "att_1",
            "status": "failed",
            "code": "500",
            "response_body": null,
            "attempt_number": 1,
            "manual": false,
            "time": "2026-07-30T18:31:50.000Z"
          }
        ]
      }
    ]
  }
}

POST/v1/webhooks/events/{eventId}/resend

Reenviar Evento

Reenvia um evento. Sem webhook_id, reenvia para todos os webhooks que receberam o evento. Com webhook_id, reenvia apenas para aquele destino. Eventos já entregues também são reenviados. Se o evento não existir no tenant, a resposta é 404 Not Found. failed conta apenas falhas na chamada de reenvio, não eventos inelegíveis.

Parâmetros de Rota

Name
eventId
Type
string
Required
obrigatório
Description
ID do evento.

Corpo

Name
webhook_id
Type
string
Description
ID do webhook de destino. Opcional.

Request

POST

/v1/webhooks/events/{eventId}/resend

curl -X POST https://api.habilitar.me/v1/webhooks/events/evt_a056V7R7NmNRjl70/resend \
  -H "x-api-key: {token}" \
  -H "Content-Type: application/json" \
  -d '{"webhook_id":"des_01J8Z3K4N5P6Q7R8S9T0"}'

Response

{
  "data": {
    "requested": 1,
    "succeeded": 1,
    "failed": 0
  }
}

POST/v1/webhooks/events/resend

Reenviar Eventos em Lote

Reenvia eventos em lote, com teto de 500 itens.

Sem event_ids, reenvia apenas eventos sem nenhuma entrega bem-sucedida. Com event_ids, reenvia esses eventos mesmo que já tenham sido entregues. webhook_id restringe o reenvio a um único destino.

Se não houver candidatos, a resposta é 200 com requested: 0. Eventos fora do tenant ou do destino pedido são omitidos, sem erro. failed conta apenas falhas na chamada de reenvio.

Corpo

Name
event_ids
Type
string[]
Description
Lista de IDs de evento. Opcional. Máximo 500.
Name
webhook_id
Type
string
Description
ID do webhook de destino. Opcional.

Request

POST

/v1/webhooks/events/resend

curl -X POST https://api.habilitar.me/v1/webhooks/events/resend \
  -H "x-api-key: {token}" \
  -H "Content-Type: application/json" \
  -d '{"event_ids":["evt_a056V7R7NmNRjl70"]}'

Response

{
  "data": {
    "requested": 3,
    "succeeded": 2,
    "failed": 1
  }
}