Referência de Webhooks

Conceito

Os Webhooks da Rovax.io são notificações HTTP POST enviadas automaticamente para a URL que você configurar sempre que um evento relevante acontece no workspace — uma mensagem recebida, uma conversa fechada, um contato criado, um canal desconectado, entre outros. Em vez de consultar a API periodicamente para verificar se algo mudou, você recebe o dado assim que o evento ocorre. Cada webhook tem um secret gerado no momento da criação, usado para assinar as entregas com HMAC-SHA256 no header X-Rovax-Signature. Isso garante que apenas a Rovax.io pode enviar eventos para o seu endpoint.

Ciclo de vida de um Webhook

criar webhook (URL + eventos + secret gerado)
    │
    ▼
active → Rovax entrega eventos para a URL
    │
    ├── evento ocorre → entrega (success ou failure)
    │       │
    │       └── falha → retentativa com backoff exponencial
    │
    ├── testar → entrega de evento sintético
    │
    ├── consultar deliveries → histórico de entregas
    │
    └── deletar → para de receber eventos

Após 5 falhas consecutivas, o webhook é marcado como failing mas continua ativo. Novos eventos continuam sendo enfileirados — você recebe um alerta por email e pode agir antes de perder dados.

Campos principais

Campo	Tipo	Descrição
`id`	string (UUID)	ID único do webhook
`url`	string	URL de destino das entregas (deve ser HTTPS)
`events`	array	Lista de categorias de eventos subscritas
`status`	enum	`active` \| `inactive` \| `failing`
`description`	string	Descrição interna do propósito do webhook
`secret`	string	Secret HMAC — exibido apenas na criação (write-once)
`created_at`	string	ISO 8601 de criação
`last_delivery_at`	string	ISO 8601 da última tentativa de entrega
`success_rate`	number	Taxa de sucesso das últimas 100 entregas (0–1)

Campos de uma Delivery

Campo	Tipo	Descrição
`id`	string (UUID)	ID da entrega
`webhook_id`	string (UUID)	Webhook que gerou a entrega
`event_type`	string	Tipo do evento entregue
`status`	enum	`success` \| `failed` \| `pending`
`http_status`	number	Código HTTP retornado pelo seu servidor
`attempt`	number	Número da tentativa (1 = primeira)
`response_time_ms`	number	Tempo de resposta em milissegundos
`delivered_at`	string	ISO 8601 da tentativa

Categorias de eventos disponíveis

Categoria	Eventos
`conversation.*`	`created`, `closed`, `reopened`, `assigned`
`message.*`	`received`, `sent`, `delivered`, `read`, `failed`
`contact.*`	`created`, `updated`, `deleted`
`agent.*`	`handoff_started`, `handoff_completed`, `transferred`
`channel.*`	`connected`, `disconnected`, `error`
`credit.*`	`low`, `depleted`
`plan.*`	`changed`

Endpoints disponíveis

Consulte a barra lateral à esquerda para a lista completa de endpoints deste grupo. Cada endpoint tem sua própria página com schema de request/response, exemplos em cURL/JS/Python e playground interativo.

Próximos passos

Primeira requisição

Se você ainda não fez sua primeira chamada, comece por aqui.

Introdução

System

Agents

Trainings

Channels

Contacts

Conversations

Custom Fields

Chats

Messages

MCPS

Webhooks

Referência de Webhooks

Conceito

Ciclo de vida de um Webhook

Campos principais

Campos de uma Delivery

Categorias de eventos disponíveis

Endpoints disponíveis

Próximos passos

Primeira requisição

​Conceito

​Ciclo de vida de um Webhook

​Campos principais

​Campos de uma Delivery

​Categorias de eventos disponíveis

​Endpoints disponíveis

​Próximos passos

Primeira requisição

Conceito

Ciclo de vida de um Webhook

Campos principais

Campos de uma Delivery

Categorias de eventos disponíveis

Endpoints disponíveis

Próximos passos