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. |
Parámetros
Sección titulada «Parámetros»| 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 |
Ejemplo
Sección titulada «Ejemplo»Contra el sandbox, con una clave onx_test_…:
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" ]}'Respuestas
Sección titulada «Respuestas»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. |
Errores
Sección titulada «Errores»Cada código tiene su explicación en Errores.
- 400
validacion - 401
clave_invalida - 403
permiso_faltante - 409
idempotencia_en_conflicto - 409
solicitud_en_curso - 409
ya_registrado - 429
limite_uso - 500
error_interno - 501
operacion_no_disponible - 503
no_disponible