Configurar Webhook

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"
  }'

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    enabled: true,
    url:     "https://meuapp.com/webhook"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "enabled": True,
        "url":     "https://meuapp.com/webhook"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "enabled": true,
        "url":     "https://meuapp.com/webhook"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    label:         "analytics-pipeline",
    enabled:       true,
    url:           "https://analytics.meuapp.com/events",
    authorization: "Bearer svc-token-xyz",
    events:        ["message.exchange", "message.status"],
    mediaBase64:   false
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "label":         "analytics-pipeline",
        "enabled":       True,
        "url":           "https://analytics.meuapp.com/events",
        "authorization": "Bearer svc-token-xyz",
        "events":        ["message.exchange", "message.status"],
        "mediaBase64":   False
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "label":         "analytics-pipeline",
        "enabled":       true,
        "url":           "https://analytics.meuapp.com/events",
        "authorization": "Bearer svc-token-xyz",
        "events":        ["message.exchange", "message.status"],
        "mediaBase64":   false
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    label:    "router",
    enabled:  true,
    url:      "https://meuapp.com/wh",
    byEvents: true,
    events:   []
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "label":    "router",
        "enabled":  True,
        "url":      "https://meuapp.com/wh",
        "byEvents": True,
        "events":   []
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "label":    "router",
        "enabled":  true,
        "url":      "https://meuapp.com/wh",
        "byEvents": true,
        "events":   []
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    label:   "analytics-pipeline",
    enabled: false
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "label":   "analytics-pipeline",
        "enabled": False
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "label":   "analytics-pipeline",
        "enabled": false
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    label:       "backup-raw",
    enabled:     true,
    url:         "https://backup.meuapp.com/raw",
    events:      ["message.exchange"],
    mediaBase64: true
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "label":       "backup-raw",
        "enabled":     True,
        "url":         "https://backup.meuapp.com/raw",
        "events":      ["message.exchange"],
        "mediaBase64": True
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "label":       "backup-raw",
        "enabled":     true,
        "url":         "https://backup.meuapp.com/raw",
        "events":      ["message.exchange"],
        "mediaBase64": true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

requerido

Nombre de la instancia (p. ej., $Instance_Name).

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

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.

boolean

requerido

Activa/desactiva el webhook. Cuando es false, los campos url, authorization, byEvents, events y mediaBase64 se limpian antes de guardar.

string

URL de destino. Requerida cuando enabled=true. Pasa por el guard SSRF (ver abajo), bloquea localhost, IPs privadas, link-local, multicast.

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.

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

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

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:

Rango	Ejemplo
Loopback	`localhost`, `127.0.0.1`, `::1`
IPv4 privada	`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
Link-local IPv4	`169.254.0.0/16`
Link-local IPv6	`fe80::/10`
Multicast / broadcast	`224.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

HTTP	`error.message`
400	`Invalid request body`
400	`URL is required when enabled is true`
400	`URL must not target localhost or private network`
400	`invalid event type: <value>`
400	`label too long (max 50 chars)`
400	`label may only contain letters, digits, underscore or dash`
401	`Invalid token`
404	`Instance not found`
409	`webhook limit reached (max 3 enabled per instance)`
429	`Rate limit exceeded. Try again later.`
500	`Failed 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.

Listar webhooks

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

Catálogo de eventos

Qué transporta cada event en data.

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Configurar Webhook

Descripción

Ejemplos

Mínimo

Con label, filtro y Authorization

byEvents = true (enrutamiento basado en URL)

Soft-disable preservando el label

Media en Base64 (respaldo crudo)

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Guard SSRF

Notas

Errores

Siguiente

Listar webhooks

Catálogo de eventos

​Descripción

​Ejemplos

​Mínimo

​Con label, filtro y Authorization

​byEvents = true (enrutamiento basado en URL)

​Soft-disable preservando el label

​Media en Base64 (respaldo crudo)

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Guard SSRF

​Notas

​Errores

​Siguiente

Listar webhooks

Catálogo de eventos

Descripción

Ejemplos

Mínimo

Con label, filtro y Authorization

byEvents = true (enrutamiento basado en URL)

Soft-disable preservando el label

Media en Base64 (respaldo crudo)

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Guard SSRF

Notas

Errores

Siguiente