Skip to main content
A cada evento assinado, o Gestio envia uma requisição POST para a URL do endpoint com o corpo JSON (envelope) e headers de identificação.

Requisição enviada

Headers

Envelope

string (uuid)
required
Identificador do log. Use para identificar duplicidades.
string
required
Código do evento, por exemplo compras.pedido-de-compra.processado.
integer
required
Versão do formato do envelope. Atualmente 1.
string (date-time)
required
Data e hora em UTC, em ISO 8601 (ex.: 2026-11-03T14:30:00Z).
boolean
Presente e igual a true somente em envios de teste. Eventos reais não têm este campo.
object
required
Dados do evento. O conteúdo depende do tipo; veja o catálogo de eventos.

Validar o token

Compare o header X-Gestio-Webhook-Token com o token que você guardou no cadastro do endpoint. Se for diferente ou estiver ausente, responda 401 e não processe o evento.
O token trafega no header da requisição, por isso o Gestio só envia webhooks para URLs HTTPS. Nunca registre o token em logs e guarde-o em um cofre de segredos.

Responder ao evento

Regras da chamada:
  • Tempo limite de 10 segundos. Responda rápido: grave o evento e processe depois, de forma assíncrona.
  • Redirecionamentos não são seguidos. Uma resposta 3xx conta como falha definitiva; cadastre a URL final.
  • O corpo da sua resposta é ignorado e não é gravado.

Novas tentativas

Falhas temporárias são repetidas com intervalos crescentes, num total de 6 tentativas (o envio inicial e mais 5): Se todas falharem, o log fica com a situação Falha e pode ser reenviado manualmente.
Cada tentativa com falha incrementa o contador de falhas do endpoint. Com 20 falhas seguidas, o endpoint é desativado automaticamente. Veja Ativar e desativar.

Boas práticas

O envio é feito pelo menos uma vez. Guarde os id já processados e ignore os repetidos. Um mesmo pedido processado de novo no Gestio gera um log com outro id; para esse caso, use os dados do evento (por exemplo, numeroDoPedido) para decidir se deve atualizar o registro.
Grave o envelope e responda 200 antes de executar regras demoradas. O limite é de 10 segundos.
Envios de teste têm teste: true e dados fictícios. Responda 2xx para confirmar a conectividade, mas não as processe como eventos reais.
Novos campos podem ser adicionados a dados sem mudar a versao do envelope. Seu sistema não deve falhar ao receber campos que não conhece.
Eventos podem chegar fora de ordem, principalmente após novas tentativas. Use ocorridoEm quando a ordem importar.