Skip to main content
O webhook da conta é a forma recomendada de receber os eventos Enterprise. Você o configura uma única vez na sua conta e ele passa a receber os eventos de todas as suas instâncias, sem precisar configurar instância por instância. O webhook por instância continua funcionando (compatível com o que já existe), mas para os eventos de teste e cobrança o webhook da conta é o preferido: um só endpoint, um só segredo de assinatura, e ele acompanha as instâncias que você cria e deleta sem trabalho extra.

Configurar o webhook da conta

Há duas formas de configurar.

Pelo painel

No painel, em /settings, você define a URL que recebe os eventos, escolhe quais eventos quer receber, vê e rotaciona o segredo de assinatura, e dispara um evento de teste para validar que o seu endpoint está recebendo e conferindo a assinatura.

Pela API

Todas as rotas aceitam o TokenAccount da conta, ou o token global passando ?account=<nome-da-conta>. GET /api/account/webhook Devolve a configuração atual. O segredo nunca volta em texto puro na leitura, apenas mascarado.
200 OK
PATCH /api/account/webhook Grava a URL, a lista de eventos e o liga ou desliga. Na primeira configuração, quando a conta ainda não tem segredo, a resposta traz o secret em texto puro uma única vez. Guarde esse valor, ele não é mostrado de novo. Para obter um novo, use a rotação de segredo.
string
Endpoint que recebe as entregas. Use HTTPS. Uma URL insegura ou não permitida é recusada com 400.
array
Os nomes dos eventos que você quer receber. Se você não enviar o campo, a conta usa os quatro eventos por padrão. Uma lista vazia ([]) significa “não receber nenhum”.
boolean
Liga ou desliga a entrega. Com false, a configuração é preservada mas nada é entregue.
string
Nome da conta. Obrigatório apenas quando você usa o token global. Com o TokenAccount, a conta já vem do próprio token.
200 OK (primeira configuração)
O secret só aparece nesta primeira resposta (e ao rotacionar). Depois disso, a leitura devolve apenas o secretMasked. Se você perder o valor, rotacione para gerar um novo.
POST /api/account/webhook/rotate-secret Gera um segredo novo e o devolve uma vez. O segredo anterior deixa de ser usado nas próximas entregas.
200 OK
POST /api/account/webhook/test Envia um evento enterprise.webhook.test para a URL configurada, para você validar a recepção e a assinatura. Responde 400 se não houver URL configurada. O evento de teste é entregue mesmo com a configuração desligada.
evento de teste entregue

Os quatro eventos

Envelope

Toda entrega tem o mesmo corpo JSON:
string
Nome do evento no formato enterprise.<tipo>, um dos quatro acima (ou enterprise.webhook.test).
string
Nome da sua conta.
string
Um resumo legível, em inglês, do que aconteceu. Bom para logs e para exibir ao seu time.
object
Os campos do evento. O conteúdo varia por tipo de evento, veja abaixo.
string
Momento da entrega, em RFC3339 (UTC).

enterprise.instance.billable

enterprise.cycle.renewed

Campos do data

O objeto data traz só os campos relevantes de cada evento.

Eventos de teste (trial.started, trial.ending)

string
Nome da instância.
string
Número de WhatsApp conectado à instância. Vem preenchido quando já há um número associado.
string
Data e hora em que o teste termina, em RFC3339.

Virada para cobrança (instance.billable)

string
Nome da instância.
string
Número de WhatsApp conectado à instância. Vem preenchido quando já há um número associado.
string
Data e hora a partir da qual a instância é cobrada, em RFC3339.

Renovação mensal (cycle.renewed)

integer
Valor efetivamente cobrado na renovação, em centavos.
integer
A base do período (o piso), em centavos.
integer
Quanto o uso passou da base, em centavos. Fica 0 quando o uso cabe na base.
string
Início do período cobrado, em RFC3339.
string
Fim do período cobrado, em RFC3339.

Validar a assinatura

Toda entrega carrega o cabeçalho X-Ryze-Signature: sha256=<hex>, um HMAC-SHA256 do corpo cru da requisição usando o segredo de assinatura da sua conta. Calcule o mesmo HMAC no seu servidor e compare, para ter certeza de que a entrega veio da RyzeAPI e não foi alterada.
Compare em tempo constante (timingSafeEqual / compare_digest), nunca com == de string. E use o corpo exatamente como recebido (os bytes crus), não o JSON reserializado, senão a assinatura não bate.
Ao rotacionar o segredo, aceite por um curto período tanto o segredo novo quanto o anterior. Assim, entregas que já estavam a caminho durante a troca continuam validando.

Webhook por instância (ainda suportado)

Antes do webhook da conta, os eventos Enterprise eram entregues no webhook da própria instância. Isso continua valendo: se o events do webhook (ou do WebSocket) de uma instância inclui os nomes enterprise.*, os eventos daquela instância também chegam ali, no mesmo envelope dos demais eventos da API. Veja Configurar webhook. Para cobrança e ciclo de vida, prefira o webhook da conta: um só endpoint recebe tudo, sem configurar instância por instância, e as entregas são assinadas.

Próximo

Controlar a cobrança

Force a cobrança de uma instância.

Perguntas frequentes

Dúvidas comuns sobre teste, cobrança e eventos.