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)
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çalhoX-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.
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 oevents 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.