Registrar Webhook

Registra una nueva URL de webhook para recibir notificaciones de eventos (envíos, DLR, respuestas).

post/webhook/add

Requisitos de la URL que registres:

Debe ser pública: no se aceptan hosts locales ni direcciones de redes privadas. Recomendamos usar HTTPS.
Al registrarla se verifica con una petición GET: cualquier respuesta que no sea 404 la aprueba (timeout de 5 segundos, sin seguir redirecciones); si no, el registro se rechaza con add_webhook_06.
Debe aceptar peticiones HEAD: antes de entregar cada evento se comprueba que la URL responde.
Debe responder HTTP 200 rápidamente cuando reciba un evento. El método de entrega (GET o POST) se configura en el panel.

Los payloads que recibirá tu servidor, los códigos de estatus de entrega y la política de reintentos están en la guía de Webhooks.

Autorización

apikeystringheaderrequerido

Cuerpo de la petición

application/json

urlstringrequerido· uri

URL pública del webhook (se recomienda HTTPS). No se aceptan hosts locales ni redes privadas. Se verifica con una petición GET al registrarla.

statusenumrequerido

Estado del webhook: '0' = deshabilitado, '1' = habilitado

enum:01

Respuesta

200Webhook registrado exitosamente

successboolean

messagestring

Mensaje de estado

statusinteger

codestring

Código de respuesta

400Error de validación. Códigos posibles: add_webhook_02 (URL no definida), add_webhook_03 (formato de URL inválido o host no permitido), add_webhook_04 (estado no definido), add_webhook_05 (estado inválido, solo 0 o 1), add_webhook_06 (la URL no respondió correctamente a la verificación).

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

Código HTTP de la respuesta

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

401No autorizado: API Key no provista, inválida o expirada

successboolean

Siempre false

messagestring

Descripción del error de autenticación en español

statusinteger

Código HTTP

codestring

Código de error de autenticación (auth_01, auth_05, auth_06, auth_07, auth_99)

403Prohibido: La dirección IP no está autorizada para acceder (IP whitelist)

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error: auth_04 (IP no autorizada en whitelist)

429Demasiadas peticiones: Límite de rate limit excedido (100 mensajes/segundo producción, 1000 envíos de prueba por día en sandbox)

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error de rate limit

500Error interno del servidor

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error interno

request_idstring· uuid

Identificador único de la petición. Inclúyelo al contactar a soporte.

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

Código	Cuándo ocurre	Qué hacer
`add_webhook_02` / `add_webhook_03`	URL ausente, con formato inválido o apuntando a un host no permitido.	Usa una URL pública válida.
`add_webhook_04` / `add_webhook_05`	`status` ausente o distinto de `0`/`1`.	Envía `"1"` (habilitado) o `"0"` (deshabilitado).
`add_webhook_06`	Tu URL no respondió a la verificación.	Asegúrate de que responda (cualquier código excepto 404) en menos de 5 segundos, sin redirecciones.
`add_webhook_07` / `add_webhook_08`	Error al guardar la configuración.	Reintenta; si persiste, contacta a soporte.

El éxito responde add_webhook_01.