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.escalated`	Uma conversa é escalada
`lead.captured`	É captado um novo lead
`lead.created`	É criado um registo de lead
`lead_form.submitted`	É submetido um formulário de lead
`handoff.requested`	É pedida a passagem para um agente humano
`csat.submitted`	É enviada uma classificação CSAT
`csat.received`	É registado um resultado CSAT
`ai.failed`	A IA não consegue produzir uma resposta
`ticket.created`	É aberto um ticket de suporte
`ticket.resolved`	É resolvido um ticket de suporte
`contact.created`	É criado um novo contacto
`contact.updated`	Um contacto é atualizado
`contact.merged`	Dois contactos são unidos
`contact.deleted`	Um contacto é eliminado

O formulário de webhook oferece também Todos os eventos, que subscreve todos os eventos acima (guardado como o wildcard *); um mesmo webhook aceita ainda uma lista de nomes de eventos separada por vírgulas.

Configuração

Aceda a Dashboard -> Programadores -> 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-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt>          # only on a retried delivery

O digest é calculado sobre <unix_timestamp>.<corpo_bruto_do_pedido>, pelo que verificar apenas o corpo nunca corresponderá. Divida o cabeçalho por ,, leia os valores t= e v1=, recalcule o HMAC-SHA256 de t + '.' + rawBody com o seu webhook secret e compare os dois digests em tempo constante. Rejeite uma entrega cujo timestamp tenha mais de alguns minutos, para que um payload capturado não possa ser repetido. Nota: Enviar teste para um URL que não é um webhook guardado é entregue sem assinatura — não existe segredo para a assinar; teste a sua verificação com um endpoint guardado.

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 -> Programadores -> Chaves API -> Criar chave API.
Inclua-a no cabeçalho Authorization:

Authorization: Bearer sk_your_api_key_here

> A chave é mostrada uma única vez. Criar uma chave exige pelo menos um âmbito (scope) — Criar fica desativado até escolher um — e o valor sk_ completo aparece uma só vez, numa caixa de diálogo que propositadamente não fecha com Escape nem ao clicar fora. Depois só o prefixo permanece legível; o resto é um hash bcrypt e não pode ser recuperado. Copie-a antes de fechar a caixa de diálogo. Se a perder, crie uma chave nova e revogue a antiga.

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.