Ir al contenido

Beta privada · apertura 23 de diciembre

Registra un webhook

POST /v1/conecta/webhooks

Registra tu endpoint para recibir eventos normalizados y firmados. Siempre espera la aprobación de una persona (por ese endpoint pasarán los mensajes de tus clientes). Ya aprobado, repite la petición con la misma Idempotency-Key: la primera respuesta 201 trae secreto; las siguientes responden ya_registrado.

Dato Valor
Permiso webhooks:administrar
Cobro No cobra.
Idempotency-Key Obligatoria
Aprobación humana Siempre: una persona la aprueba en el panel, sin importar la configuración de la clave.
Herramienta MCP No se ofrece a agentes.
Nombre En Requerido Tipo Descripción
Idempotency-Key header Sí string Identifica una operación para que repetirla no la duplique. Si repites la petición con la misma clave y el mismo cuerpo, recibes la misma respuesta; con otro cuerpo, idempotencia_en_conflicto. Se guarda 24 horas.
X-Request-Id header No string Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte.

application/json, obligatorio. Los campos anidados van con punto y los de listas con []. No se aceptan campos desconocidos.

Campo Tipo Requerido Descripción
url string (uri) Sí Tu endpoint. Debe responder 2xx en menos de 10 segundos.
eventos “mensaje.recibido” | “mensaje.estado” | “conexion.estado” | “plantilla.estado”[] Sí
descripcion string No

Contra el sandbox, con una clave onx_test_…:

Ventana de terminal
curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/webhooks" \
-H "Authorization: Bearer onx_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"url": "https://ejemplo.com",
"eventos": [
"mensaje.recibido"
]
}'

Webhook creado; guarda secreto ahora.

Campo Tipo Requerido Descripción
webhook object Sí Webhook de tu sistema.
webhook.id string Sí Identificador que empieza con whk_.
webhook.url string (uri) Sí URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave).
webhook.eventos “mensaje.recibido” | “mensaje.estado” | “conexion.estado” | “plantilla.estado”[] Sí
webhook.descripcion string | null Sí
webhook.estado “activo” | “pausado” Sí Se pausa solo si tu endpoint falla muchas veces seguidas.
webhook.creado_en string (date-time) Sí Fecha y hora ISO 8601 con la zona de Lima (-05:00).
webhook.secreto_rotado_en string (date-time) | null Sí
secreto string Sí Secreto para verificar X-Nexum-Signature. Se muestra solo esta vez.

Espera la aprobación de una persona.

Campo Tipo Requerido Descripción
estado “requiere_confirmacion” Sí
operacion_id string Sí Úsalo en GET /v1/confirmaciones/{id} para saber si se aprobó.
confirmacion_url string (uri) Sí Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual.
consulta_url string Sí Ruta para consultar el estado.
expira_en string (date-time) Sí Antes de esta hora hay que aprobarla Y repetir la petición; si no, vence y no se hace.
mensaje string Sí Qué falta, en palabras para una persona.

Cada código tiene su explicación en Errores.