Saltar al contenido principal
GET
/
api
/
events
/
getWebhook
/
:instance
Consultar Webhooks
curl --request GET \
  --url https://api.example.com/api/events/getWebhook/:instance \
  --header 'token: <token>'
{
  "webhooks": [
    {}
  ],
  "webhook": {}
}

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í

​
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

IntentoPró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)

ColumnaDescripción
idBIGSERIAL PK
instance_nameNombre de la instancia
urlDestino final (ya con sufijo /event-name si byEvents)
payloadBYTEA, cuerpo JSON del evento
auth_headerAuthorization configurado (cifrado en reposo)
event_typeNombre del evento (message.exchange etc.)
statuspending | delivered | failed
attemptsContador de intentos
max_attemptsDefault 5
next_retry_atPróxima ventana de intento
last_errorÚltimo mensaje de error del consumidor
created_at / updated_atTimestamps

​
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

HTTPerror.messageAplica a
400label too long (max 50 chars)?label=
400label may only contain letters, digits, underscore or dash?label=
401Invalid tokenambos
404Instance not foundambos
404Webhook not configured for this label?label=
429Rate limit exceeded. Try again later.ambos
500Failed to get instanceambos
500Failed to list webhook configurationssin query
Envoltorio: 
{
  "success": false,
  "error": { "message": "Webhook not configured for this label" }
}

​
Siguiente

Configurar webhook

POST /api/events/webhook/:instance

Catálogo de eventos

Esquemas de los 6 tipos de eventos.