Ir al contenido

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

  1. Lee la cabecera: t=<segundos unix>,v1=<firma>. Durante una rotación de secreto llegan dos v1.
  2. Arma el texto <t>.<cuerpo crudo> con el cuerpo exacto, sin volver a serializarlo.
  3. Calcula HMAC-SHA256 de ese texto con tu secreto whsec_… y pásalo a hexadecimal.
  4. Compáralo en tiempo constante con algún v1. Rechaza si no coincide o si t difiere 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.

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_.