Pular para o conteúdo principal
GET
/
api
/
events
/
getWebhook
/
:instance
Verificar 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 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

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

ColunaDescrição
idBIGSERIAL PK
instance_nameNome da instância
urlDestino final (já com sufixo /event-name se byEvents)
payloadBYTEA, corpo JSON do evento
auth_headerAuthorization configurado (encriptado at-rest)
event_typeNome do evento (message.exchange etc.)
statuspending | delivered | failed
attemptsContador de tentativas
max_attemptsDefault 5
next_retry_atPróxima janela de tentativa
last_errorÚltima mensagem de erro do consumer
created_at / updated_atTimestamps

​
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

HTTPerror.messageAplica em
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 configurationssem query
Envelope: 
{
  "success": false,
  "error": { "message": "Webhook not configured for this label" }
}

​
Próximo

Configurar webhook

POST /api/events/webhook/:instance

Catálogo de eventos

Schemas dos 6 tipos de evento.