Listar webhooks

GET/v1/webhooks

Para desarrolladores

Descripción

Lista los webhooks de la instancia, con el estado de su última entrega. El secreto de firma no se incluye: solo se entrega al crear el webhook y al rotar su secreto.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope webhooks:read. Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Request

Query params:

pageinteger

Número de página; la primera es la 1. Default: 1.

page_sizeinteger

Tamaño de página, 1–100. Default: 20.

Response

200 OKDevuelve una página de resultados: data con los elementos y pagination para pedir la siguiente. Cada elemento tiene los campos que siguen.

idintegersiempre presente

Identificador del webhook.

namestringsiempre presente

—

urlstringsiempre presente

Endpoint que recibe las entregas.

eventsstring[] | nullsiempre presente

Tipos de evento que recibe. null recibe todos. Ver Eventos.

is_activebooleansiempre presente

false si el webhook está pausado.

last_success_atstring (date-time) | nullsiempre presente

Última entrega respondida con 2xx.

last_failure_atstring (date-time) | nullsiempre presente

Última entrega fallida.

last_status_codeinteger | nullsiempre presente

Código HTTP de la última entrega. null si no hubo respuesta, por timeout o error de conexión.

consecutive_failuresintegersiempre presente

Entregas fallidas seguidas desde el último éxito.

failing_sincestring|nullsiempre presente

Momento del primer fallo de la racha en curso, o null si la última entrega fue exitosa.

auto_paused_atstring (date-time) | nullsiempre presente

Momento en que el webhook se pausó por fallos persistentes. null si no está pausado automáticamente.

previous_secret_expires_atstring (date-time) | nullsiempre presente

Hasta cuándo el secreto anterior a la última rotación firma junto al vigente. null si no hay un secreto anterior vigente.

created_atstring (date-time)siempre presente

—

updated_atstring (date-time)siempre presente

Última modificación de la configuración del webhook. Una entrega no la cambia.

Notas

• Los webhooks se devuelven en orden de creación.
• consecutive_failures mayor que cero indica un endpoint que está fallando. Qué cuenta como fallo y cómo se reintenta está en Respuesta y reintentos.
• Un webhook con auto_paused_at informado se pausó por fallos persistentes y no recibe entregas hasta que se reanude con PATCH /v1/webhooks/{id}. Ver Pausa automática.

Request

curl -X GET "https://$API_HOST/v1/webhooks" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"data": [
  {
    "id": 3,
    "name": "CRM de ventas",
    "url": "https://hooks.example.com/fidelizador",
    "events": [
      "mail.sent",
      "mail.bounced"
    ],
    "is_active": true,
    "last_success_at": "2026-09-13T12:00:04Z",
    "last_failure_at": null,
    "last_status_code": 200,
    "consecutive_failures": 0,
    "failing_since": null,
    "auto_paused_at": null,
    "previous_secret_expires_at": null,
    "created_at": "2026-09-10T15:30:00Z",
    "updated_at": "2026-09-10T15:30:00Z"
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 1,
  "total_pages": 1
}
}