Consultar Webhooks

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

Descripción

Endpoint de lectura. Sin query, retorna todos los webhooks (habilitados y deshabilitados) de la instancia. Con ?label=<name>, retorna el único webhook con ese label (o 404).

Ejemplos

Listar todos

Sin query string, retorna el array webhooks[] con todos los webhooks de la instancia (habilitados y deshabilitados), ordenados alfabéticamente por label.

curl -X GET "https://ryzeapi.cloud/api/events/getWebhook/$Instance_Name" \
  -H "token: $Token_Instance"

await fetch(`https://ryzeapi.cloud/api/events/getWebhook/${process.env.Instance_Name}`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/events/getWebhook/{os.environ['Instance_Name']}",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/events/getWebhook/"+os.Getenv("Instance_Name"), nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Uno específico

Pasando ?label=analytics-pipeline, retorna solo el webhook con ese label en el campo webhook del envoltorio (o 404 si no existe).

curl -X GET "https://ryzeapi.cloud/api/events/getWebhook/$Instance_Name?label=analytics-pipeline" \
  -H "token: $Token_Instance"

await fetch(`https://ryzeapi.cloud/api/events/getWebhook/${process.env.Instance_Name}?label=analytics-pipeline`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/events/getWebhook/{os.environ['Instance_Name']}?label=analytics-pipeline",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/events/getWebhook/"+os.Getenv("Instance_Name")+"?label=analytics-pipeline", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Default explícito

Obtiene el webhook default pasando ?label=default. Útil cuando creaste el webhook sin especificar un label y quieres leer solo esa entrada en lugar de la lista completa.

curl -X GET "https://ryzeapi.cloud/api/events/getWebhook/$Instance_Name?label=default" \
  -H "token: $Token_Instance"

await fetch(`https://ryzeapi.cloud/api/events/getWebhook/${process.env.Instance_Name}?label=default`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/events/getWebhook/{os.environ['Instance_Name']}?label=default",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/events/getWebhook/"+os.Getenv("Instance_Name")+"?label=default", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Respuesta exitosa

Sin ?label=, retorna webhooks[] (ordenados alfabéticamente por label, siempre presente, regresa como [] si no existe ningún webhook, y también incluye los que tienen enabled=false para inspección operacional). Con ?label=<name>, retorna el objeto único en webhook (misma forma que POST). El authorization se descifra cuando ENCRYPTION_KEY está configurado; si la clave fue rotada y algún valor no puede descifrarse, el campo se retorna cifrado en lugar de fallar la solicitud.

200 OK (list, no ?label=)

{
  "success": true,
  "message": "Webhook configurations retrieved",
  "webhooks": [
    {
      "label":         "analytics-pipeline",
      "enabled":       true,
      "url":           "https://analytics.meuapp.com/events",
      "authorization": "Bearer svc-token-xyz",
      "byEvents":      false,
      "events":        ["message.exchange", "message.status"],
      "mediaBase64":   false
    },
    {
      "label":       "default",
      "enabled":     true,
      "url":         "https://meuapp.com/webhook",
      "byEvents":    false,
      "events":      [],
      "mediaBase64": false
    },
    {
      "label":       "legacy",
      "enabled":     false,
      "url":         "",
      "byEvents":    false,
      "events":      [],
      "mediaBase64": false
    }
  ]
}

200 OK (?label=analytics-pipeline)

{
  "success": true,
  "message": "Webhook configuration retrieved",
  "webhook": {
    "label":         "analytics-pipeline",
    "enabled":       true,
    "url":           "https://analytics.meuapp.com/events",
    "authorization": "Bearer svc-token-xyz",
    "byEvents":      false,
    "events":        ["message.exchange", "message.status"],
    "mediaBase64":   false
  }
}

array

Presente solo cuando no hay ?label=. Ordenado alfabéticamente por label. Siempre se retorna incluso cuando no existe ningún webhook (webhooks: []).

object

Presente solo cuando se usa ?label=<name>. Misma forma que POST.

Parámetros de ruta

string

requerido

Nombre de la instancia.

Cabeceras

string

requerido

TokenAccount o TokenInstance.

Parámetros de consulta

string

Cuando está presente, retorna un único webhook (webhook en el envoltorio). Cuando está ausente, retorna la lista (webhooks[]).Pasar ?label= (vacío) sigue considerándose “presente” → se convierte en "default" y busca la fila con ese label.

El listado incluye enabled=false, los operadores ven el historial completo. Para listar solo los activos, filtra del lado del cliente por w.enabled === true.
authorization descifrado: si ENCRYPTION_KEY está configurado y el valor está cifrado en reposo, el repositorio lo descifra antes de retornar. Si la clave fue rotada y un valor no puede descifrarse, el campo se retorna cifrado (con una advertencia en el log) en lugar de fallar la solicitud.

Entrega: cola, retry, DLQ

La entrega del webhook es asíncrona y persistida. Cada evento que coincide con un webhook se encola en webhook_queue y es procesado por workers paralelos.

Flujo

EventsService.sendWebhook()
   └─► webhook_queue.Enqueue()        [INSERT row, status=pending]
                                          │
WebhookDispatcher (4 workers + janitor) ──┘
   ├─► ClaimNext()  (FOR UPDATE SKIP LOCKED)
   ├─► HTTP POST + SSRF re-check
   ├─► MarkDelivered (2xx)
   ├─► MarkRetry (4xx except 408/429, redeliver; 408/429/5xx, retry)
   └─► MarkFailed (attempts > max_attempts → DLQ)

Janitor: every 15min, DELETE rows delivered > 24h ago.

Backoff exponencial

Intento	Próximo retry
1 (fail)	+1s
2 (fail)	+5s
3 (fail)	+30s
4 (fail)	+5min
5 (fail)	+30min
6+	+1h (cap)

Después de max_attempts (default 5), status se vuelve failed (DLQ). La fila no se elimina automáticamente, los operadores pueden inspeccionar last_error y reencolar manualmente (UPDATE webhook_queue SET status='pending', next_retry_at=now()).

Tabla `webhook_queue` (resumen ops)

Columna	Descripción
`id`	`BIGSERIAL` PK
`instance_name`	Nombre de la instancia
`url`	Destino final (ya con sufijo `/event-name` si `byEvents`)
`payload`	`BYTEA`, cuerpo JSON del evento
`auth_header`	`Authorization` configurado (cifrado en reposo)
`event_type`	Nombre del evento (`message.exchange` etc.)
`status`	`pending` \| `delivered` \| `failed`
`attempts`	Contador de intentos
`max_attempts`	Default 5
`next_retry_at`	Próxima ventana de intento
`last_error`	Último mensaje de error del consumidor
`created_at` / `updated_at`	Timestamps

Cabeceras entregadas

Cada POST a tu webhook llega con:

POST <url> HTTP/1.1
Host: <your-host>
Content-Type: application/json
Authorization: <config.authorization>      # if configured
User-Agent: RyzeAPI/<version>

{ "event": "...", "data": { ... }, "instanceData": { ... } }

No hay HMAC automático. La validación del origen es responsabilidad del consumidor, configura un authorization (Bearer token, API key) y valídalo en tu endpoint.

Errores

HTTP	`error.message`	Aplica a
400	`label too long (max 50 chars)`	`?label=`
400	`label may only contain letters, digits, underscore or dash`	`?label=`
401	`Invalid token`	ambos
404	`Instance not found`	ambos
404	`Webhook not configured for this label`	`?label=`
429	`Rate limit exceeded. Try again later.`	ambos
500	`Failed to get instance`	ambos
500	`Failed to list webhook configurations`	sin query

Envoltorio:

{
  "success": false,
  "error": { "message": "Webhook not configured for this label" }
}

Configurar webhook

POST /api/events/webhook/:instance

Catálogo de eventos

Esquemas de los 6 tipos de eventos.

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Consultar Webhooks

Descripción

Ejemplos

Listar todos

Uno específico

Default explícito

Respuesta exitosa

Parámetros de ruta

Cabeceras

Parámetros de consulta

Entrega: cola, retry, DLQ

Flujo

Backoff exponencial

Tabla `webhook_queue` (resumen ops)

Cabeceras entregadas

Errores

Siguiente

Configurar webhook

Catálogo de eventos

​Descripción

​Ejemplos

​Listar todos

​Uno específico

​Default explícito

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Parámetros de consulta

​Entrega: cola, retry, DLQ

​Flujo

​Backoff exponencial

​Tabla webhook_queue (resumen ops)

​Cabeceras entregadas

​Errores

​Siguiente

Configurar webhook

Catálogo de eventos

Descripción

Ejemplos

Listar todos

Uno específico

Default explícito

Respuesta exitosa

Parámetros de ruta

Cabeceras

Parámetros de consulta

Entrega: cola, retry, DLQ

Flujo

Backoff exponencial

Tabla `webhook_queue` (resumen ops)

Cabeceras entregadas

Errores

Siguiente