> ## Documentation Index > Fetch the complete documentation index at: https://docs.gestio.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Pelo sistema > Cadastre e acompanhe os webhooks pela tela de Integrações do Gestio, sem escrever código. 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. > [!NOTE] > > 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](https://mintcdn.com/gestio/Hmr8GCDqBR5YPzNN/images/webhooks/lista-de-webhooks.webp?fit=max\&auto=format\&n=Hmr8GCDqBR5YPzNN\&q=85\&s=e471b688e64f683d108bf457b5baebb6) Integrações → Webhooks: a lista de webhooks da empresa. Cada linha da lista traz: | Coluna | O que mostra | | - | - | | **Webhook** | O nome do webhook e, abaixo, a URL de destino. | | **Eventos** | Quantos eventos o webhook assina e de quais módulos. | | **Falhas consecutivas** | Quantas tentativas de envio falharam em sequência. Volta a `0` em qualquer envio com sucesso. Com **20**, o webhook é desativado automaticamente. | | **Atualizado em** | Data da última alteração (ou do cadastro, se nunca foi alterado). | | **Ativo** | Chave liga/desliga. Webhooks inativos não recebem novos eventos. | | **Ações** | Menu com as operações da linha. | 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**. > [!TIP] > > 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](https://mintcdn.com/gestio/Hmr8GCDqBR5YPzNN/images/webhooks/novo-webhook.webp?fit=max\&auto=format\&n=Hmr8GCDqBR5YPzNN\&q=85\&s=644c2dd20c1f213ad9fc8d487162831c) 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](https://docs.gestio.com.br/pages/webhooks/gerenciar-endpoints.md#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](https://docs.gestio.com.br/pages/webhooks/eventos.md). **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. > [!WARNING] > > 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](https://mintcdn.com/gestio/Hmr8GCDqBR5YPzNN/images/webhooks/configuracao-do-webhook.webp?fit=max\&auto=format\&n=Hmr8GCDqBR5YPzNN\&q=85\&s=4f834a9c2133fb30bbefc4369da3a7a6) Painel lateral do webhook, aba Configuração. O painel lateral tem duas abas: **Configuração** e **Logs**. Na Configuração você encontra: **Nome** `obrigatório` Nome do webhook, até 100 caracteres. **URL de destino** `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. **Token de autenticação** Exibido mascarado (`****894c`, os 4 últimos caracteres). O botão **Rotacionar** gera um novo token. **Webhook ativo** Chave liga/desliga. Webhooks inativos não recebem eventos. **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 de ações ![Menu Ações aberto com as opções Editar, Ver logs, Enviar teste, Rotacionar token e Excluir](https://mintcdn.com/gestio/Hmr8GCDqBR5YPzNN/images/webhooks/menu-de-acoes.webp?fit=max\&auto=format\&n=Hmr8GCDqBR5YPzNN\&q=85\&s=1028b649d138c540e12a15c36939bed3) Menu Ações de uma linha da lista. | Ação | O que faz | | - | - | | **Editar** | Abre o painel lateral na aba Configuração. | | **Ver logs** | Abre o painel lateral na aba Logs. | | **Enviar teste** | Mostra o payload de exemplo de cada evento assinado e envia na hora. | | **Rotacionar token** | Gera um novo token, invalidando o atual. | | **Excluir** | Remove o webhook, os eventos assinados e **todos os logs** dele. | > [!WARNING] > > 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](https://mintcdn.com/gestio/Hmr8GCDqBR5YPzNN/images/webhooks/modal-enviar-teste.webp?fit=max\&auto=format\&n=Hmr8GCDqBR5YPzNN\&q=85\&s=e7e73fb339f70769239e84720fe42fad) 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. > [!NOTE] > > 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](https://mintcdn.com/gestio/Hmr8GCDqBR5YPzNN/images/webhooks/modal-rotacionar-token.webp?fit=max\&auto=format\&n=Hmr8GCDqBR5YPzNN\&q=85\&s=0474ad1f53879e5ea9183228050de628) 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. > [!TIP] > > 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](https://mintcdn.com/gestio/Hmr8GCDqBR5YPzNN/images/webhooks/logs-payload.webp?fit=max\&auto=format\&n=Hmr8GCDqBR5YPzNN\&q=85\&s=d52cce10f6d152ca7e5f9b6ec64668aa) Aba Payload: o envelope exato enviado ao destino. ![Aba Resposta de um log com status HTTP 405, erro e aviso de tentativas esgotadas](https://mintcdn.com/gestio/Hmr8GCDqBR5YPzNN/images/webhooks/logs-resposta.webp?fit=max\&auto=format\&n=Hmr8GCDqBR5YPzNN\&q=85\&s=0a724ec38b68bbc09ca57f05105ebe23) Aba Resposta: o resultado da última tentativa. > [!NOTE] > > 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. > [card] [Gerenciar endpoints pela API](https://docs.gestio.com.br/pages/webhooks/gerenciar-endpoints.md) > > Cadastrar, alterar, excluir, rotacionar o token, testar e reenviar via API. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.