Verificar Webhooks

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim

Descrição

Endpoint de leitura. Sem query, retorna todos os webhooks (habilitados e desabilitados) da instância. Com ?label=<nome>, retorna o único webhook desse label (ou 404).

Exemplos

Listar todos

Sem query string, retorna o array webhooks[] com todos os webhooks da instância (habilitados e desabilitados), ordenado alfabeticamente por label.

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

Um específico

Passando ?label=analytics-pipeline, retorna apenas o webhook desse label no campo webhook do envelope (ou 404 se não existir).

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

Default explícito

Busca o webhook padrão informando ?label=default. Útil quando você criou o webhook sem especificar label e quer ler somente essa entrada em vez da lista completa.

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

Resposta de sucesso

Sem ?label=, retorna webhooks[] (ordenado alfabeticamente por label, sempre presente, vem [] se nenhum webhook existir, e inclui também os com enabled=false para inspeção operacional). Com ?label=<nome>, retorna o objeto único em webhook (mesmo shape do POST). O authorization vem descriptografado quando ENCRYPTION_KEY está configurada; se a chave foi rotacionada e algum valor não decifra, o campo retorna criptografado em vez de derrubar o request.

200 OK (lista, sem ?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 apenas quando não há ?label=. Ordenado alfabeticamente por label. Sempre retornado mesmo sem nenhum webhook (webhooks: []).

webhook

object

Presente apenas quando há ?label=<nome>. Mesmo shape do POST.

Parâmetros de rota

instance

string

obrigatório

Nome da instância.

Headers

token

string

obrigatório

TokenAccount ou TokenInstance.

Query parameters

label

string

Quando presente, retorna um único webhook (webhook no envelope). Ausente, retorna a lista (webhooks[]).Passar ?label= (vazio) ainda é considerado “presente” → vira "default" e busca a linha desse label.

Listagem inclui enabled=false, operadores veem o histórico completo. Para listar só ativos, filtre no cliente por w.enabled === true.
authorization descriptografado: se ENCRYPTION_KEY está configurada e o valor estiver criptografado at-rest, o repositório descriptografa antes de retornar. Se a chave foi rotacionada e algum valor não decifra, o campo retorna criptografado (com warning no log) em vez de derrubar o request.

Entrega: queue, retry, DLQ

A entrega de webhooks é assíncrona e persistida. Cada evento que matcha um webhook é enfileirado em webhook_queue e processado por workers em paralelo.

Fluxo

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 exceto 408/429, reentregar; 408/429/5xx, retry)
   └─► MarkFailed (attempts > max_attempts → DLQ)

Janitor: a cada 15min, DELETE de rows delivered há > 24h.

Backoff exponencial

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

Após max_attempts (default 5), status vira failed (DLQ). A linha não é deletada automaticamente, operadores podem inspecionar last_error e re-enfileirar manualmente (UPDATE webhook_queue SET status='pending', next_retry_at=now()).

Tabela `webhook_queue` (resumo para ops)

Coluna	Descrição
`id`	`BIGSERIAL` PK
`instance_name`	Nome da instância
`url`	Destino final (já com sufixo `/event-name` se `byEvents`)
`payload`	`BYTEA`, corpo JSON do evento
`auth_header`	`Authorization` configurado (encriptado at-rest)
`event_type`	Nome do evento (`message.exchange` etc.)
`status`	`pending` \| `delivered` \| `failed`
`attempts`	Contador de tentativas
`max_attempts`	Default 5
`next_retry_at`	Próxima janela de tentativa
`last_error`	Última mensagem de erro do consumer
`created_at` / `updated_at`	Timestamps

Headers entregues

Cada POST ao seu webhook chega com:

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

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

Não há HMAC automático. A validação de origem é responsabilidade do consumidor, configure um authorization (Bearer token, API key) e valide no seu endpoint.

Erros

HTTP	`error.message`	Aplica em
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`	sem query

Envelope:

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

Configurar webhook

POST /api/events/webhook/:instance

Catálogo de eventos

Schemas dos 6 tipos de evento.

​Descrição

​Exemplos

​Listar todos

​Um específico

​Default explícito

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Query parameters

​Entrega: queue, retry, DLQ

​Fluxo

​Backoff exponencial

​Tabela webhook_queue (resumo para ops)

​Headers entregues

​Erros

​Próximo

Configurar webhook

Catálogo de eventos

Descrição

Exemplos

Listar todos

Um específico

Default explícito

Resposta de sucesso

Parâmetros de rota

Headers

Query parameters

Entrega: queue, retry, DLQ

Fluxo

Backoff exponencial

Tabela `webhook_queue` (resumo para ops)

Headers entregues

Erros

Próximo