POST /v1/webhooks

POST/v1/webhooks

Para desarrolladores

Descripción

Registra un endpoint que recibe los eventos de los correos de la instancia. La respuesta incluye el secreto de firma (whsec_…) con el que se firman las entregas, y es la única vez que se entrega.

El formato de las entregas, la verificación de la firma y los reintentos están en Webhooks (pendiente de publicación).

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope webhooks:write. Formato: Bearer FD.<key_id>.<token>.

X-Instance-Slugstringheaderobligatorio

Request

Body:

{
  "name": "CRM de ventas",
  "url": "https://hooks.example.com/fidelizador",
  "events": ["mail.sent", "mail.bounced"],
  "is_active": true
}

namestringobligatorio

1–255 caracteres.

urlstringobligatorio

Endpoint que recibe las entregas, hasta 1024 caracteres. Debe ser https://, sin usuario ni contraseña, y su host debe resolver a direcciones públicas. Ver Requisitos del endpoint *(pendiente de publicación)*.

eventsstring[], enum: `mail.sent | mail.bounced | mail.dropped | mail.opened | mail.clicked | mail.unsubscribed | mail.resubscribed | mail.complained` | null

Tipos de evento que recibe; al menos uno si se envía la lista, y los repetidos se ignoran. Omitido o null: recibe todos.

is_activeboolean

false crea el webhook pausado. Default: true.

Response

201 CreatedDevuelve el objeto creado. El header Location trae su URL (ver Headers).

idintegerobligatorio

Identificador del webhook creado.

namestringobligatorio

—

urlstringobligatorio

—

eventsstring[] | nullobligatorio

Los tipos de evento, sin repetidos. null recibe todos.

is_activebooleanobligatorio

—

last_success_atstring (date-time) | nullobligatorio

null hasta la primera entrega exitosa.

last_failure_atstring (date-time) | nullobligatorio

null hasta la primera entrega fallida.

last_status_codeinteger | nullobligatorio

null hasta la primera entrega.

consecutive_failuresintegerobligatorio

0 al crear.

auto_paused_atstring (date-time) | nullobligatorio

null al crear.

previous_secret_expires_atstring (date-time) | nullobligatorio

null al crear: todavía no hubo una rotación.

created_atstring (date-time)obligatorio

—

updated_atstring (date-time)obligatorio

—

secretstringobligatorio

Secreto de firma. Solo se entrega en esta respuesta.

Errores

Código	Cuándo
402	Crear el webhook supera la cantidad de webhooks que permite el plan (plan_webhooks_limit_exceeded).
422	El body no es válido, o la URL no cumple los requisitos: errors[].code es webhook_url_insecure si no usa https, o webhook_url_not_allowed si no resuelve a una dirección pública.

Detalle completo en Errores de negocio y Errores genéricos.

Notas

• El secreto debe guardarse de inmediato: no se puede recuperar después. Si se pierde, se rota.
• El secreto lo genera la plataforma. Un campo secret en el body se ignora, igual que cualquier otro campo no documentado.
• El cupo del plan cuenta todos los webhooks de la instancia, activos o pausados.
• Para comprobar que el endpoint recibe y verifica la firma sin esperar un evento real, se usa el evento de prueba.

Request

curl -X POST "https://$API_HOST/v1/webhooks" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "name": "CRM de ventas",
  "url": "https://hooks.example.com/fidelizador",
  "events": [
    "mail.sent",
    "mail.bounced"
  ]
}'

Response

{
"id": 3,
"name": "CRM de ventas",
"url": "https://hooks.example.com/fidelizador",
"events": [
  "mail.sent",
  "mail.bounced"
],
"is_active": true,
"last_success_at": null,
"last_failure_at": null,
"last_status_code": null,
"consecutive_failures": 0,
"auto_paused_at": null,
"previous_secret_expires_at": null,
"created_at": "2026-09-14T10:00:00Z",
"updated_at": "2026-09-14T10:00:00Z",
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}