Saltar al contenido principal
POST
/
api
/
events
/
webhook
/
:instance
Configurar Webhook
curl --request POST \
  --url https://api.example.com/api/events/webhook/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "label": "<string>",
  "enabled": true,
  "url": "<string>",
  "authorization": {},
  "byEvents": true,
  "events": [
    "<string>"
  ],
  "mediaBase64": true
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Auth: TokenAccount o TokenInstance • Rate limit: Global (100/min) • Idempotente: sí (upsert por label)

​
Descripción

Crea o actualiza la fila (instance, label) en webhook_configs. Cada instancia acepta hasta 3 webhooks habilitados simultáneamente, identificados por un label libre. Los webhooks con enabled=false se mantienen en la base de datos pero no cuentan para el límite y no reciben entregas. Casos de uso:
  • Crear un nuevo webhook: envía un label aún no utilizado.
  • Actualizar uno existente: envía el mismo label, todos los nuevos campos sobrescriben los antiguos.
  • Soft-disable: envía el mismo label con {"enabled": false} (limpia url, authorization, events, mediaBase64, pero preserva la fila).
  • Migración paralela: ejecuta el webhook viejo mientras validas el nuevo bajo un label diferente; una vez confirmado, desactiva el viejo.

​
Ejemplos

​
Mínimo

Habilita el webhook default apuntando a https://meuapp.com/webhook. Sin events, recibe los 6 tipos; sin authorization, no envía cabecera de auth. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url":     "https://meuapp.com/webhook"
  }'

​
Con label, filtro y Authorization

Crea un webhook llamado analytics-pipeline que solo recibe message.exchange y message.status, envía la cabecera Authorization: Bearer svc-token-xyz en cada entrega y desactiva el respaldo en base64. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":         "analytics-pipeline",
    "enabled":       true,
    "url":           "https://analytics.meuapp.com/events",
    "authorization": "Bearer svc-token-xyz",
    "events":        ["message.exchange", "message.status"],
    "mediaBase64":   false
  }'

​
byEvents = true (enrutamiento basado en URL)

Activa byEvents: true para que cada entrega se envíe con el nombre del evento como sufijo en la URL (p. ej., https://meuapp.com/wh/message.exchange), permitiendo enrutamiento del lado servidor por endpoint sin inspeccionar el payload. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":    "router",
    "enabled":  true,
    "url":      "https://meuapp.com/wh",
    "byEvents": true,
    "events":   []
  }'
# Deliveries go to https://meuapp.com/wh/message.exchange, /group.flow, ...

​
Soft-disable preservando el label

Desactiva el webhook analytics-pipeline enviando solo enabled: false. La fila queda en la base de datos pero url, authorization, events y mediaBase64 se limpian, y la entrada deja de contar para el límite de 3 webhooks activos. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":   "analytics-pipeline",
    "enabled": false
  }'

​
Media en Base64 (respaldo crudo)

Configura un webhook dedicado al respaldo que solo recibe message.exchange con mediaBase64: true, de modo que cada mensaje con media incluya el contenido binario codificado en base64 dentro del payload. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":       "backup-raw",
    "enabled":     true,
    "url":         "https://backup.meuapp.com/raw",
    "events":      ["message.exchange"],
    "mediaBase64": true
  }'

​
Respuesta exitosa

La respuesta retorna el objeto webhook con la configuración efectivamente persistida (label, enabled, url, authorization, byEvents, events, mediaBase64), refleja el body de la solicitud después del upsert. Cuando enabled=false, los campos url, authorization, events y mediaBase64 regresan limpios. El dispatcher comienza a usar la nueva configuración inmediatamente (el caché interno de 30s se invalida al guardar).
200 OK
{
  "success": true,
  "message": "Webhook configured successfully",
  "webhook": {
    "label":         "default",
    "enabled":       true,
    "url":           "https://meuapp.com/webhook",
    "authorization": "Bearer secret-key-123",
    "byEvents":      false,
    "events":        ["message.exchange", "call.update"],
    "mediaBase64":   true
  }
}

​
Parámetros de ruta

​
instance
string
requerido
Nombre de la instancia (p. ej., $Instance_Name).

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.
​
Content-Type
string
requerido
application/json

​
Cuerpo de la solicitud

​
label
string
predeterminado:"default"
Identificador local. Máx. 50 caracteres; acepta [a-zA-Z0-9_-]. Vacío u omitido se convierte en "default". Permite múltiples webhooks por instancia.
​
enabled
boolean
requerido
Activa/desactiva el webhook. Cuando es false, los campos url, authorization, byEvents, events y mediaBase64 se limpian antes de guardar.
​
url
string
URL de destino. Requerida cuando enabled=true. Pasa por el guard SSRF (ver abajo), bloquea localhost, IPs privadas, link-local, multicast.
​
authorization
string | null
predeterminado:"null"
Contenido literal de la cabecera Authorization enviada en cada entrega (p. ej., Bearer secret-key-123). Cifrado en reposo con AES-256-GCM cuando ENCRYPTION_KEY está configurado.
​
byEvents
boolean
predeterminado:"false"
Si es true, la URL recibe el sufijo /<event-name> en cada entrega, útil para enrutamiento basado en endpoints sin inspeccionar el payload (https://app/wh/message.exchange).
​
events
string[]
predeterminado:"[]"
Filtro. Array vacío = recibir los 6 tipos. Cada entrada debe estar en {message.exchange, message.status, call.update, group.flow, instance.state, label.update}.
​
mediaBase64
boolean
predeterminado:"false"
Cuando es true, los eventos message.exchange con media incluyen media.base64 (aumenta el payload, puede exceder 100KB).

​
Guard SSRF

La url se valida al momento de la configuración y antes de cada entrega. Bloquea destinos que apunten a infraestructura interna:
RangoEjemplo
Loopbacklocalhost, 127.0.0.1, ::1
IPv4 privada10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
Link-local IPv4169.254.0.0/16
Link-local IPv6fe80::/10
Multicast / broadcast224.0.0.0/4, 255.255.255.255
Si necesitas probar contra un servidor local en desarrollo, expónlo a través de un túnel público (ngrok, cloudflared, localhost.run), el guard SSRF está activo en todos los entornos.

​
Notas

  • authorization vacío vs. null: envía null u omítelo para saltar la cabecera. Una cadena vacía "" resultaría en una cabecera Authorization: vacía, que algunos proxies rechazan.
  • enabled=false limpia los campos: re-habilitar el mismo label después requiere reenviar la url (y cualquier otro campo que quieras preservar).
  • No hay DELETE: para “remover” un webhook, haz POST con {"enabled": false} manteniendo el label. Los operadores pueden inspeccionar/limpiar la fila directamente en la base de datos cuando sea necesario.
  • Cifrado opcional: si ENCRYPTION_KEY no está configurado, authorization se almacena en texto plano. En producción, siempre configura la clave.
  • Caché invalidado: la nueva configuración se vuelve visible para el dispatcher inmediatamente (el TTL interno de 30s se invalida al guardar).

​
Errores

HTTPerror.message
400Invalid request body
400URL is required when enabled is true
400URL must not target localhost or private network
400invalid event type: <value>
400label too long (max 50 chars)
400label may only contain letters, digits, underscore or dash
401Invalid token
404Instance not found
409webhook limit reached (max 3 enabled per instance)
429Rate limit exceeded. Try again later.
500Failed to get instance
Envoltorio: 
{
  "success": false,
  "error": { "message": "URL must not target localhost or private network" }
}
La verificación del límite de 3 webhooks solo se aplica al crear una nueva fila con enabled=true. Editar una fila existente (mismo label) nunca dispara el límite.

​
Siguiente

Listar webhooks

GET /api/events/getWebhook/:instance, todos o por ?label=.

Catálogo de eventos

Qué transporta cada event en data.