Webhooks e API REST

O Conviro disponibiliza webhooks para notificações de eventos em tempo real e uma API REST para aceder programaticamente a todas as funcionalidades da plataforma.

Webhooks

O que são webhooks?

Os webhooks enviam um pedido HTTP POST para o seu servidor sempre que ocorre um evento específico no Conviro. Assim, pode reagir em tempo real, sem recorrer a polling.

Eventos disponíveis

Evento	Quando é despoletado
`message.new`	É enviada uma nova mensagem (pelo visitante ou pelo bot)
`session.started`	Começa uma nova sessão de conversa
`session.closed`	Uma conversa é fechada
`session.handoff`	Uma conversa é transferida para um agente humano
`lead.captured`	É captado um novo lead
`contact.created`	É criado um novo contacto
`ticket.created`	É aberto um ticket de suporte
`csat.submitted`	É submetida uma avaliação CSAT

Configuração

Aceda a Dashboard -> Settings -> Webhooks.
Clique em Add Webhook.
Introduza o URL do seu endpoint (tem de ser HTTPS).
Selecione os eventos que pretende receber.
Clique em Save.

Segurança: assinatura HMAC-SHA256

Todos os payloads de webhook são assinados com HMAC-SHA256 através do seu webhook secret. Verifique a assinatura no seu servidor para garantir a autenticidade:

X-Conviro-Signature: sha256=<hex_digest>

Compare este cabeçalho com o digest HMAC-SHA256 do corpo bruto do pedido, calculado com o seu webhook secret.

Política de novas tentativas

Se o seu endpoint devolver um código de estado diferente de 2xx, o Conviro repete a tentativa até 3 vezes com backoff exponencial (1 min, 5 min, 30 min).

API REST

Autenticação

Gere uma chave de API em Dashboard -> Settings -> API Keys -> Create Key.
Inclua-a no cabeçalho Authorization:

Authorization: Bearer sk_your_api_key_here

Principais endpoints

Método	Endpoint	Descrição
GET	`/api/chatbots`	Lista todos os chatbots
GET	`/api/chatbots/:id`	Obtém os detalhes de um chatbot
GET	`/api/sessions`	Lista as sessões (com filtros)
GET	`/api/sessions/:id/messages`	Obtém as mensagens de uma sessão
POST	`/api/sessions/:id/messages`	Envia uma mensagem para uma sessão
GET	`/api/contacts`	Lista os contactos
POST	`/api/contacts`	Cria um contacto
GET	`/api/leads`	Lista os leads
POST	`/api/leads`	Cria um lead
GET	`/api/analytics/overview`	Obtém o resumo das analytics

Limites de pedidos

Plano Free: 60 pedidos/minuto
Starter: 120 pedidos/minuto
Pro: 300 pedidos/minuto
Growth+: 600 pedidos/minuto

Os cabeçalhos com o limite de pedidos são incluídos em todas as respostas:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200

Documentação completa

Visite /developers para consultar a referência completa da API, com exemplos de pedido e resposta.