Beta privada · apertura 23 de diciembre
Eventos de webhook
Evento de Nexum Conecta hacia tu sistema
Enviamos cada evento con POST a la URL de tu webhook, con el cuerpo en JSON y la cabecera X-Nexum-Signature.
Cómo verificar la firma
- Lee la cabecera:
t=<segundos unix>,v1=<firma>. Durante una rotación de secreto llegan dosv1. - Arma el texto
<t>.<cuerpo crudo>con el cuerpo exacto, sin volver a serializarlo. - Calcula HMAC-SHA256 de ese texto con tu secreto
whsec_…y pásalo a hexadecimal. - Compáralo en tiempo constante con algún
v1. Rechaza si no coincide o sitdifiere en más de 300 segundos de tu reloj.
Cómo responder
Responde 2xx en menos de 10 segundos y procesa después. Si fallas, reintentamos hasta 8 veces con espera creciente; luego el webhook se pausa y puedes reenviar desde /v1/conecta/entregas. Un mismo evento puede llegar más de una vez: usa su id para no procesarlo dos veces.
Campos del evento
Sección titulada «Campos del evento»| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
id |
string | Sí | Único por evento: úsalo para no procesar dos veces el mismo. |
creado_en |
string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
version |
“v1” | Sí | |
conexion_id |
string | null | Sí | |
tipo |
“mensaje.recibido” | Sí | |
datos |
object | Sí | |
datos.mensaje |
object | No | Mensaje enviado o recibido. |
datos.mensaje.id |
string | No | Identificador que empieza con msg_. |
datos.mensaje.conexion_id |
string | No | Identificador que empieza con con_. |
datos.mensaje.conversacion_id |
string | No | Identificador que empieza con cnv_. |
datos.mensaje.canal |
“whatsapp” | “instagram” | “messenger” | No | |
datos.mensaje.direccion |
“saliente” | “entrante” | No | |
datos.mensaje.tipo |
“texto” | “media” | “plantilla” | “interactivo” | “otro” | No | |
datos.mensaje.texto |
string | null | No | |
datos.mensaje.media |
object | null | No | En mensajes entrantes, la URL es nuestra y vence en unas horas. |
datos.mensaje.media.tipo |
“imagen” | “video” | “audio” | “documento” | No | |
datos.mensaje.media.url |
string (uri) | No | |
datos.mensaje.media.nombre_archivo |
string | null | No | |
datos.mensaje.media.leyenda |
string | null | No | |
datos.mensaje.plantilla |
object | null | No | |
datos.mensaje.plantilla.nombre |
string | No | |
datos.mensaje.plantilla.idioma |
string | No | |
datos.mensaje.estado |
“en_cola” | “enviado” | “entregado” | “leido” | “fallido” | “incierto” | “recibido” | No | incierto: el proveedor no confirmó; revisa antes de reenviar. recibido: mensaje entrante. |
datos.mensaje.error |
object | null | No | |
datos.mensaje.error.codigo |
string | No | |
datos.mensaje.error.mensaje |
string | No | |
datos.mensaje.creado_en |
string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
datos.mensaje.actualizado_en |
string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
datos.conversacion |
object | No | Conversación con un contacto en un canal. |
datos.conversacion.id |
string | No | Identificador que empieza con cnv_. |
datos.conversacion.conexion_id |
string | No | Identificador que empieza con con_. |
datos.conversacion.canal |
“whatsapp” | “instagram” | “messenger” | No | |
datos.conversacion.contacto |
object | No | |
datos.conversacion.contacto.nombre |
string | null | No | |
datos.conversacion.contacto.telefono |
string | null | No | |
datos.conversacion.contacto.usuario |
string | null | No | Usuario de Instagram, si aplica. |
datos.conversacion.ventana |
object | No | Ventana de atención: mientras está abierta puedes escribir libre; si no, solo plantillas. |
datos.conversacion.ventana.abierta |
boolean | No | |
datos.conversacion.ventana.cierra_en |
string (date-time) | null | No | |
datos.conversacion.ventana.tipo |
“24h” | “72h” | null | No | 72h cuando el contacto llegó por un anuncio. |
datos.conversacion.no_leidos |
integer | No | |
datos.conversacion.ultimo_mensaje_en |
string (date-time) | null | No | |
datos.conversacion.creada_en |
string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
datos.mensaje_id |
string | No | Identificador que empieza con msg_. |
datos.conversacion_id |
string | No | Identificador que empieza con cnv_. |
datos.estado |
“en_cola” | “enviado” | “entregado” | “leido” | “fallido” | “incierto” | “recibido” | No | incierto: el proveedor no confirmó; revisa antes de reenviar. recibido: mensaje entrante. |
datos.error |
object | null | No | |
datos.error.codigo |
string | No | |
datos.error.mensaje |
string | No | |
datos.actualizado_en |
string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
datos.conexion |
object | No | Conexión de un número de WhatsApp, una cuenta de Instagram o una página de Messenger. |
datos.conexion.id |
string | No | Identificador que empieza con con_. |
datos.conexion.proveedor |
“zernio” | “ycloud” | “meta” | No | Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración. |
datos.conexion.canal |
“whatsapp” | “instagram” | “messenger” | No | |
datos.conexion.nombre |
string | No | |
datos.conexion.estado |
“pendiente” | “activa” | “desconectada” | “error” | No | |
datos.conexion.telefono |
string | null | No | |
datos.conexion.cuenta |
string | null | No | Usuario de Instagram o página de Facebook, si aplica. |
datos.conexion.alta_url |
string (uri) | null | No | Mientras está pendiente: dónde termina el alta una persona. |
datos.conexion.creada_en |
string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
datos.conexion.ultima_prueba_en |
string (date-time) | null | No | |
datos.plantilla |
object | No | Plantilla de mensaje. |
datos.plantilla.id |
string | No | Identificador que empieza con plt_. |
datos.plantilla.conexion_id |
string | No | Identificador que empieza con con_. |
datos.plantilla.nombre |
string | No | |
datos.plantilla.idioma |
string | No | |
datos.plantilla.categoria |
“utilidad” | “marketing” | “autenticacion” | No | |
datos.plantilla.estado |
“pendiente” | “aprobada” | “rechazada” | “pausada” | “deshabilitada” | No | |
datos.plantilla.encabezado |
string | null | No | |
datos.plantilla.cuerpo |
string | No | |
datos.plantilla.pie |
string | null | No | |
datos.plantilla.botones |
object[] | No | |
datos.plantilla.botones[].tipo |
“respuesta_rapida” | “url” | “telefono” | No | |
datos.plantilla.botones[].texto |
string | No | |
datos.plantilla.variables |
integer | No | Cuántas variables espera el cuerpo. |
datos.plantilla.motivo_rechazo |
string | null | No | |
datos.plantilla.creada_en |
string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
datos.plantilla.actualizada_en |
string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
datos.webhook_id |
string | No | Identificador que empieza con whk_. |