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"

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"

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"

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

webhooks

array

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

webhook

object

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

Parámetros de ruta

instance

string

requerido

Nombre de la instancia.

Cabeceras

token

string

requerido

TokenAccount o TokenInstance.

Parámetros de consulta

label

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.

​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