Skip to main content
El webhook de la cuenta es la forma recomendada de recibir los eventos Enterprise. Lo configura una sola vez en su cuenta y pasa a recibir los eventos de todas sus instancias, sin necesidad de configurar instancia por instancia. El webhook por instancia sigue funcionando (compatible con lo que ya existe), pero para los eventos de prueba y cobro el webhook de la cuenta es el preferido: un solo endpoint, un solo secreto de firma, y sigue a las instancias que crea y elimina sin trabajo extra.

Configurar el webhook de la cuenta

Hay dos formas de configurarlo.

Desde el panel

En el panel, en /settings, define la URL que recibe los eventos, elige qué eventos quiere recibir, ve y rota el secreto de firma, y dispara un evento de prueba para confirmar que su endpoint está recibiendo y verificando la firma.

Vía la API

Todas las rutas aceptan el TokenAccount de la cuenta, o el token global pasando ?account=<nombre-de-la-cuenta>. GET /api/account/webhook Devuelve la configuración actual. El secreto nunca vuelve en texto plano en la lectura, solo enmascarado.
200 OK
PATCH /api/account/webhook Guarda la URL, la lista de eventos y lo activa o desactiva. En la primera configuración, cuando la cuenta aún no tiene secreto, la respuesta trae el secret en texto plano una sola vez. Guarde ese valor, no se muestra de nuevo. Para obtener uno nuevo, rote el secreto.
string
Endpoint que recibe las entregas. Use HTTPS. Una URL insegura o no permitida se rechaza con 400.
array
Los nombres de los eventos que quiere recibir. Si no envía el campo, la cuenta usa los cuatro eventos por defecto. Una lista vacía ([]) significa “no recibir ninguno”.
boolean
Activa o desactiva la entrega. Con false, la configuración se conserva pero no se entrega nada.
string
Nombre de la cuenta. Obligatorio solo cuando usa el token global. Con el TokenAccount, la cuenta ya viene del propio token.
200 OK (primera configuración)
El secret solo aparece en esta primera respuesta (y al rotarlo). Después de eso, la lectura devuelve solo el secretMasked. Si pierde el valor, rote para generar uno nuevo.
POST /api/account/webhook/rotate-secret Genera un secreto nuevo y lo devuelve una vez. El secreto anterior deja de usarse en las siguientes entregas.
200 OK
POST /api/account/webhook/test Envía un evento enterprise.webhook.test a la URL configurada, para que valide la recepción y la firma. Responde 400 si no hay URL configurada. El evento de prueba se entrega incluso con la configuración desactivada.
evento de prueba entregado

Los cuatro eventos

Envelope

Cada entrega tiene el mismo cuerpo JSON:
string
Nombre del evento en el formato enterprise.<tipo>, uno de los cuatro de arriba (o enterprise.webhook.test).
string
Nombre de su cuenta.
string
Un resumen legible, en inglés, de lo que ocurrió. Útil para logs y para mostrar a su equipo.
object
Los campos del evento. El contenido varía según el tipo de evento, vea abajo.
string
Momento de la entrega, en RFC3339 (UTC).

enterprise.instance.billable

enterprise.cycle.renewed

Campos de data

El objeto data trae solo los campos relevantes de cada evento.

Eventos de prueba (trial.started, trial.ending)

string
Nombre de la instancia.
string
Número de WhatsApp conectado a la instancia. Viene poblado cuando ya hay un número asociado.
string
Fecha y hora en que termina la prueba, en RFC3339.

Paso a cobro (instance.billable)

string
Nombre de la instancia.
string
Número de WhatsApp conectado a la instancia. Viene poblado cuando ya hay un número asociado.
string
Fecha y hora a partir de la cual se cobra la instancia, en RFC3339.

Renovación mensual (cycle.renewed)

integer
Monto efectivamente cobrado en la renovación, en centavos.
integer
La base del período (el piso), en centavos.
integer
Cuánto pasó el uso de la base, en centavos. Es 0 cuando el uso cabe dentro de la base.
string
Inicio del período cobrado, en RFC3339.
string
Fin del período cobrado, en RFC3339.

Validar la firma

Cada entrega lleva el encabezado X-Ryze-Signature: sha256=<hex>, un HMAC-SHA256 del cuerpo crudo de la solicitud usando el secreto de firma de su cuenta. Calcule el mismo HMAC en su servidor y compare, para asegurarse de que la entrega vino de RyzeAPI y no fue alterada.
Compare en tiempo constante (timingSafeEqual / compare_digest), nunca con un == de cadena. Y use el cuerpo exactamente como se recibió (los bytes crudos), no el JSON reserializado, de lo contrario la firma no coincidirá.
Al rotar el secreto, acepte durante un breve período tanto el secreto nuevo como el anterior. Así, las entregas que ya estaban en camino durante el cambio siguen validando.

Webhook por instancia (aún soportado)

Antes del webhook de la cuenta, los eventos Enterprise se entregaban en el webhook de la propia instancia. Eso sigue vigente: si la lista events del webhook (o del WebSocket) de una instancia incluye los nombres enterprise.*, los eventos de esa instancia también llegan ahí, en el mismo envelope que los demás eventos de la API. Vea Configurar webhook. Para cobro y ciclo de vida, prefiera el webhook de la cuenta: un solo endpoint recibe todo, sin configurar instancia por instancia, y las entregas van firmadas.

Siguiente

Controlar el cobro

Fuerce el cobro de una instancia.

Preguntas frecuentes

Dudas comunes sobre prueba, cobro y eventos.