O webhook receiver é o endpoint do Retuno que recebe os eventos que você envia. Uma única URL, um método (POST), um formato (JSON).
Endpoint
- Método:
POST.
Content-Type: application/json.- URL base: exibida em Configurações → Webhook no painel. A mesma URL recebe eventos de gatilho e tracking.
Autenticação
O endpoint exige um token por organização, obtido em Configurações → Webhook no painel. Cada organização tem um único token ativo por vez; quando necessário, use o botão Rotacionar token na mesma página para gerar um novo e revogar o anterior.
O token é enviado no header Authorization — sem prefixo Bearer.
curl -X POST https://<endpoint-do-painel> \
-H "Authorization: SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"event": "subscription.cancelled",
"customer": {
"external_id": "usr_42",
"name": "Maria Silva",
"email": "maria@empresa.com.br",
"phone": "+5511999999999"
}
}'
O token dá acesso de escrita a todos os eventos da sua conta. Guarde em local seguro no seu sistema e nunca exponha no frontend ou em logs.
Formato de resposta
Sucesso retorna 200 com corpo:
{
"ok": true,
"data": { "verified": true }
}
{
"ok": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Corpo da requisição inválido."
}
}
| Campo | Tipo | Descrição |
|---|
error.code | string | Código estável do erro, para lógica programática. |
error.message | string | Mensagem em pt-BR, apresentável ao usuário final. |
error.details | object | Opcional, contexto técnico. |
error.field_errors | object | Opcional, mapa de campo → mensagem em erros de validação. |
Códigos HTTP
| Código | Significado | error.code |
|---|
200 | Sucesso. | — |
401 | Token ausente ou inválido. | WEBHOOK_TOKEN_MISSING, WEBHOOK_TOKEN_INVALID |
422 | Corpo da requisição inválido (payload mal formado ou validação de schema falhou). | VALIDATION_ERROR |
429 | Rate limit excedido. | RATE_LIMIT_EXCEEDED |
Rate limit
O endpoint aplica rate limit por token. Ao exceder, a resposta é 429 com error.code igual a RATE_LIMIT_EXCEEDED. O Retuno não envia o header Retry-After hoje — no seu cliente, aplique um backoff conservador (por exemplo, alguns segundos dobrando a cada tentativa) antes de tentar novamente.
Próximo passo
Veja o schema do payload em Envelope e formato de evento. 
