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)
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 encabezadoX-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.
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 listaevents 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.