Skip to main content
Dentro do Gestio, os webhooks ficam em Integrações → aba Webhooks. Por essa tela é possível fazer tudo o que a API faz: cadastrar, alterar, ativar, desativar, excluir, rotacionar o token, enviar um teste, consultar os logs e reenviá-los.
A aba Webhooks é visível apenas para usuários administradores da empresa. Se você não a encontra, peça ao administrador do Gestio da sua empresa.

A lista de webhooks

Tela de Integrações, aba Webhooks, com a lista de webhooks cadastrados

Integrações → Webhooks: a lista de webhooks da empresa.

Cada linha da lista traz: Acima da lista ficam a busca (filtra por nome e URL), o botão Documentação (abre esta documentação) e o botão Novo webhook.
Clicar em qualquer ponto da linha abre o painel lateral do webhook, o mesmo da opção Editar.

Cadastrar um webhook

Painel lateral Novo webhook com os campos Nome e URL de destino em branco e a seção Eventos

Painel de cadastro, aberto pelo botão Novo webhook.

1

Clique em Novo webhook

O painel lateral abre em branco, com os campos de configuração.
2

Preencha o nome

Um nome para você identificar a integração, por exemplo ERP — pedidos de compra. Até 100 caracteres.
3

Informe a URL de destino

A URL do seu sistema que vai receber os eventos. Precisa ser HTTPS e apontar para um endereço público na internet — veja as regras da URL.
4

Marque os eventos

Na seção Eventos, marque os eventos que esse webhook deve receber, agrupados por módulo. É obrigatório marcar pelo menos um. Veja o catálogo de eventos.
5

Clique em Criar webhook

O Gestio gera o token de autenticação e o exibe em seguida.
6

Copie o token

O token completo aparece uma única vez. Copie e guarde no cofre de segredos do seu sistema antes de clicar em Concluir — o botão só libera depois que você copia.
Se o token for perdido, não há como recuperá-lo: será preciso rotacionar o token e atualizar o seu sistema com o novo valor.

Editar, token e eventos

Painel lateral do webhook com os campos Nome, URL de destino, Token de autenticação, a chave Webhook ativo e a seção Eventos

Painel lateral do webhook, aba Configuração.

O painel lateral tem duas abas: Configuração e Logs. Na Configuração você encontra:
obrigatório
Nome do webhook, até 100 caracteres.
obrigatório
Apenas HTTPS. Respostas 2xx em até 10 segundos contam como entregues. A nova URL vale somente para os logs criados depois da alteração: logs antigos, mesmo reenviados, continuam indo para a URL gravada neles.
Exibido mascarado (****894c, os 4 últimos caracteres). O botão Rotacionar gera um novo token.
Chave liga/desliga. Webhooks inativos não recebem eventos.
Lista de eventos agrupados por módulo, com o código do evento abaixo da descrição. Pelo menos um precisa estar marcado.
Depois de alterar qualquer campo, clique em Salvar alterações. Cancelar descarta as alterações. No topo do painel ficam o nome, a URL (com botão de copiar), a etiqueta Ativo/Inativo e o ícone ?, que abre as dúvidas frequentes sobre webhooks.
Menu Ações aberto com as opções Editar, Ver logs, Enviar teste, Rotacionar token e Excluir

Menu Ações de uma linha da lista.

A exclusão é definitiva e leva junto todo o histórico de logs do webhook. Para apenas parar de receber eventos, use a chave Ativo — assim o histórico é preservado.

Enviar um teste

Modal Enviar teste com o payload de exemplo do evento compras.pedido-de-compra.processado

O modal mostra o payload de exemplo antes de enviar.

Em Ações → Enviar teste (ou em Mais ações, no rodapé do painel), o Gestio mostra o payload de exemplo de cada evento assinado antes de enviar. Ao confirmar com Enviar teste:
  • é criado e enviado um log por evento assinado, com o código real do evento;
  • o envio acontece na hora, e o resultado aparece na aba Logs;
  • funciona mesmo com o webhook inativo, para você validar antes de ativá-lo;
  • o envelope tem teste: true e dados fictícios;
  • o resultado não altera o contador de falhas consecutivas nem a desativação automática.
Se o webhook não tiver nenhum evento marcado, o botão de envio fica desabilitado: marque ao menos um evento na aba Configuração.

Rotacionar o token

Modal Rotacionar token avisando que o token atual deixa de valer imediatamente

Confirmação da rotação do token.

Em Ações → Rotacionar token (ou no botão Rotacionar ao lado do campo de token, na aba Configuração), o Gestio avisa que o token atual deixa de valer imediatamente. Ao confirmar em Rotacionar, o novo token é exibido uma única vez; copie-o e atualize o sistema que recebe os eventos logo em seguida. A partir da rotação, todos os logs novos e os reenvios de logs antigos passam a usar o novo token.
Para trocar o token sem perder eventos, aceite temporariamente o token antigo e o novo no seu receptor, rotacione e, depois de atualizar a configuração, deixe de aceitar o antigo.

Acompanhar os logs

A aba Logs do painel lateral lista os logs do webhook, do mais recente para o mais antigo.
  • Filtro por situação: Todas, Entregue, Falha ou Pendente.
  • Atualizar: o ícone de recarregar, à direita do filtro.
  • Carregar mais: traz a próxima página do histórico.
Cada linha mostra o evento, a data/hora, o número da tentativa, a duração da última tentativa em milissegundos e o status HTTP (em vermelho quando falhou). Ao clicar, o log expande em duas abas:
  • Payload — o envelope JSON exato que foi enviado, com botão de copiar.
  • Resposta — status HTTP, erro, data da última tentativa, data do envio concluído e a próxima tentativa automática, quando houver.
Aba Logs com um log expandido mostrando o payload JSON enviado

Aba Payload: o envelope exato enviado ao destino.

Aba Resposta de um log com status HTTP 405, erro e aviso de tentativas esgotadas

Aba Resposta: o resultado da última tentativa.

Só o resultado da última tentativa é guardado, e o corpo da resposta do seu sistema não é armazenado.

Reenviar um log

Dentro do log expandido, o botão Reenviar repete o envio mantendo o mesmo id e o mesmo payload. Vale para logs em qualquer situação. O webhook precisa estar ativo para reenviar.

Desativação automática

Quando um webhook acumula 20 tentativas de envio com falha seguidas, o Gestio o desativa sozinho e mostra um aviso no topo da lista. Os logs que ainda estavam pendentes são encerrados como Falha com o erro “Endpoint desativado”. Para voltar a receber: corrija o problema no seu sistema, teste o webhook e ligue a chave Ativo de novo. A reativação zera o contador de falhas.

E pela API?

Tudo o que está nesta tela também está disponível nas rotas /v2/webhooks da API de Clientes — inclusive para automatizar o provisionamento dos webhooks dos seus clientes.

Gerenciar endpoints pela API

Cadastrar, alterar, excluir, rotacionar o token, testar e reenviar via API.