Pular para o conteúdo principal
POST
/
api
/
events
/
webhook
/
:instance
Definir Webhook
curl --request POST \
  --url https://api.example.com/api/events/webhook/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "label": "<string>",
  "enabled": true,
  "url": "<string>",
  "authorization": {},
  "byEvents": true,
  "events": [
    "<string>"
  ],
  "mediaBase64": true
}
'
Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim (upsert por label)

​
Descrição

Cria ou atualiza a linha (instance, label) em webhook_configs. Cada instância aceita até 3 webhooks habilitados simultâneos, identificados por um label livre. Webhooks com enabled=false ficam preservados no banco mas não contam para o limite e não recebem entregas. Casos de uso:
  • Criar novo webhook: envie um label ainda não usado.
  • Atualizar existente: envie o mesmo label, todos os campos novos sobrescrevem os antigos.
  • Soft-disable: envie o mesmo label com {"enabled": false} (limpa url, authorization, events, mediaBase64, mas preserva a linha).
  • Migração paralela: rode o webhook antigo enquanto valida o novo num label diferente; quando confirmar, desabilita o antigo.

​
Exemplos

​
Mínimo

Habilita o webhook default apontando para https://meuapp.com/webhook. Sem events, recebe os 6 tipos; sem authorization, não envia header de autenticação. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url":     "https://meuapp.com/webhook"
  }'

​
Com label, filtro e Authorization

Cria um webhook nomeado analytics-pipeline que recebe apenas message.exchange e message.status, envia o header Authorization: Bearer svc-token-xyz em cada entrega e desliga o backup em base64. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":         "analytics-pipeline",
    "enabled":       true,
    "url":           "https://analytics.meuapp.com/events",
    "authorization": "Bearer svc-token-xyz",
    "events":        ["message.exchange", "message.status"],
    "mediaBase64":   false
  }'

​
byEvents = true (roteamento por URL)

Liga byEvents: true para que cada delivery seja enviada com o nome do evento como sufixo da URL (ex.: https://meuapp.com/wh/message.exchange), permitindo rotear no servidor por endpoint sem precisar inspecionar o payload. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":    "router",
    "enabled":  true,
    "url":      "https://meuapp.com/wh",
    "byEvents": true,
    "events":   []
  }'
# Entregas vão para https://meuapp.com/wh/message.exchange, /group.flow, ...

​
Soft-disable preservando o label

Desliga o webhook analytics-pipeline enviando apenas enabled: false. A linha permanece no banco mas url, authorization, events e mediaBase64 são zerados, e a entrada deixa de contar para o limite de 3 webhooks ativos. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":   "analytics-pipeline",
    "enabled": false
  }'

​
Mídia em base64 (backup raw)

Configura um webhook dedicado a backup que recebe somente message.exchange com mediaBase64: true, fazendo cada mensagem com mídia incluir o conteúdo binário codificado em base64 dentro do payload. 
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":       "backup-raw",
    "enabled":     true,
    "url":         "https://backup.meuapp.com/raw",
    "events":      ["message.exchange"],
    "mediaBase64": true
  }'

​
Resposta de sucesso

A resposta devolve o objeto webhook com a configuração efetivamente persistida (label, enabled, url, authorization, byEvents, events, mediaBase64), espelha o body do request após o upsert. Quando enabled=false, os campos url, authorization, events e mediaBase64 voltam zerados. O dispatcher passa a usar a nova config imediatamente (o cache interno de 30s é invalidado no save).
200 OK
{
  "success": true,
  "message": "Webhook configured successfully",
  "webhook": {
    "label":         "default",
    "enabled":       true,
    "url":           "https://meuapp.com/webhook",
    "authorization": "Bearer secret-key-123",
    "byEvents":      false,
    "events":        ["message.exchange", "call.update"],
    "mediaBase64":   true
  }
}

​
Parâmetros de rota

​
instance
string
obrigatório
Nome da instância (ex.: $Instance_Name).

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance.
​
Content-Type
string
obrigatório
application/json

​
Request body

​
label
string
padrão:"default"
Identificador local. Máx. 50 chars; aceita [a-zA-Z0-9_-]. Vazio ou omitido vira "default". Permite múltiplos webhooks por instância.
​
enabled
boolean
obrigatório
Liga/desliga o webhook. Quando false, os campos url, authorization, byEvents, events e mediaBase64 são zerados antes de salvar.
​
url
string
URL de destino. Obrigatória quando enabled=true. Passa pelo SSRF guard (ver abaixo), bloqueia localhost, IPs privados, link-local, multicast.
​
authorization
string | null
padrão:"null"
Conteúdo literal do header Authorization enviado em cada delivery (ex.: Bearer secret-key-123). Encriptado at-rest com AES-256-GCM quando ENCRYPTION_KEY está configurada.
​
byEvents
boolean
padrão:"false"
Se true, a URL recebe sufixo /<event-name> em cada entrega, útil para roteamento por endpoint sem inspecionar o payload (https://app/wh/message.exchange).
​
events
string[]
padrão:"[]"
Filtro. Array vazio = recebe todos os 6 tipos. Cada entrada precisa estar em {message.exchange, message.status, call.update, group.flow, instance.state, label.update}.
​
mediaBase64
boolean
padrão:"false"
Quando true, eventos message.exchange com mídia incluem media.base64 (aumenta payload, pode passar de 100KB).

​
SSRF guard

A url é validada na configuração e antes de cada delivery. Bloqueia destinos que apontem para a infraestrutura interna:
FaixaExemplo
Loopbacklocalhost, 127.0.0.1, ::1
IPv4 privado10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
Link-local IPv4169.254.0.0/16
Link-local IPv6fe80::/10
Multicast / broadcast224.0.0.0/4, 255.255.255.255
Se você precisa testar contra um servidor local em desenvolvimento, exponha-o por um túnel público (ngrok, cloudflared, localhost.run), a SSRF guard é ativa em todos os ambientes.

​
Notas

  • authorization vazio vs. null: envie null ou omita para não enviar header. String vazia "" resultaria em Authorization: vazio, que alguns proxies rejeitam.
  • enabled=false zera os campos: re-habilitar o mesmo label depois exige re-enviar a url (e os outros campos que você quiser preservar).
  • Não há DELETE: para “remover” um webhook, faça POST com {"enabled": false} mantendo o label. Operadores podem inspecionar/limpar a linha diretamente no banco quando necessário.
  • Encriptação opcional: se ENCRYPTION_KEY não está configurada, o authorization é armazenado em texto puro. Em produção, sempre configure a chave.
  • Cache invalidado: a config nova fica visível para o dispatcher imediatamente (TTL interno de 30s é invalidado no save).

​
Erros

HTTPerror.message
400Invalid request body
400URL is required when enabled is true
400URL must not target localhost or private network
400invalid event type: <valor>
400label too long (max 50 chars)
400label may only contain letters, digits, underscore or dash
401Invalid token
404Instance not found
409webhook limit reached (max 3 enabled per instance)
429Rate limit exceeded. Try again later.
500Failed to get instance
Envelope: 
{
  "success": false,
  "error": { "message": "URL must not target localhost or private network" }
}
O check do limite de 3 só é aplicado ao criar uma linha nova com enabled=true. Editar uma linha já existente (mesmo label) nunca aciona o limite.

​
Próximo

Listar webhooks

GET /api/events/getWebhook/:instance, todos ou por ?label=.

Catálogo de eventos

O que cada event carrega no data.