Visão geral - Gestio

Webhooks permitem que o Gestio avise o seu sistema quando algo acontece, sem que você precise consultar a API de tempos em tempos. Você cadastra uma URL HTTPS, escolhe os eventos que quer receber e, a cada ocorrência, o Gestio envia um POST com os dados do evento para essa URL.

Duas formas de gerenciar

O cadastro e a manutenção dos webhooks podem ser feitos de duas formas. As duas usam os mesmos dados: um webhook criado pela tela aparece na API e vice-versa.

Pela tela do Gestio

Em Integrações → Webhooks. Indicado para quem vai apenas configurar a URL, acompanhar os logs e reenviá-los.

Pela API de Clientes

Rotas /v2/webhooks. Indicado para provisionar webhooks de forma automatizada, a partir do seu próprio sistema.

Como funciona

Cadastre um webhook

Informe um nome, a URL HTTPS do seu sistema e os eventos que deseja assinar. O Gestio devolve um token exclusivo do webhook, exibido uma única vez.

Teste a integração

Envie um teste para receber um payload de exemplo de cada evento assinado, com dados fictícios e o campo teste: true. O resultado aparece na hora.

Receba os eventos

A cada evento, o Gestio envia um POST com o envelope JSON e os headers X-Gestio-*. Valide o token e responda com HTTP 2xx.

Acompanhe os logs

Consulte o histórico de logs de cada webhook, veja o resultado da última tentativa e reenvie quando necessário.

Conceitos

Conceito	Descrição
Webhook (endpoint)	URL HTTPS do seu sistema que recebe os eventos. Tem nome, lista de eventos assinados, token e situação (ativo ou inativo).
Evento	Algo que aconteceu no Gestio, identificado por um código como `compras.pedido-de-compra.processado`.
Log	O registro de cada envio de um evento para um webhook. Tem um id próprio (o campo `idEntrega` na API), situação (`Pendente`, `Entregue` ou `Falha`) e o resultado da última tentativa.
Envelope	O corpo JSON enviado, com `id`, `tipo`, `versao`, `ocorridoEm` e `dados`.
Token	Segredo do webhook enviado no header `X-Gestio-Webhook-Token`, para você confirmar que a chamada veio do Gestio.

Garantias do envio

Pelo menos uma vez: um mesmo evento pode chegar mais de uma vez (reenvio manual ou nova tentativa após falha). Use o id do envelope para evitar processamento duplicado.
Sem ordem garantida: os eventos podem chegar fora da ordem em que os eventos ocorreram. Use ocorridoEm quando a ordem importar.
Novas tentativas automáticas: se o seu sistema estiver fora do ar, o Gestio tenta de novo por cerca de 8 horas e meia. Veja Receber eventos.
Isolamento por empresa: cada empresa só vê e recebe os webhooks e os logs dela. Um id de outra empresa responde como inexistente.
Somente HTTPS: o token vai no header da requisição, por isso o Gestio só envia para URLs HTTPS públicas.

Por onde começar

Eventos

Catálogo de eventos e o conteúdo de dados de cada um.

Receber eventos

Envelope, headers, validação do token e novas tentativas.

Testar e reenviar

Payload de exemplo, logs e reenvio.

Referência das rotas

As 12 rotas /v2/webhooks na aba Referência, com playground para testar.