> ## 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.

# Visão geral

> Receba no seu sistema, em tempo real, os eventos que acontecem no 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.

> [card] [Pela tela do Gestio](https://docs.gestio.com.br/pages/webhooks/pelo-sistema.md)
>
> Em **Integrações → Webhooks**. Indicado para quem vai apenas configurar a URL, acompanhar os logs e reenviá-los.

> [card] [Pela API de Clientes](https://docs.gestio.com.br/pages/webhooks/gerenciar-endpoints.md)
>
> Rotas `/v2/webhooks`. Indicado para provisionar webhooks de forma automatizada, a partir do seu próprio sistema.

## Como funciona

**1. 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.

**2. 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.

**3. 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`.

**4. 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](https://docs.gestio.com.br/pages/webhooks/receber-eventos.md#novas-tentativas).
* **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

> [card] [Eventos](https://docs.gestio.com.br/pages/webhooks/eventos.md)
>
> Catálogo de eventos e o conteúdo de `dados` de cada um.

> [card] [Receber eventos](https://docs.gestio.com.br/pages/webhooks/receber-eventos.md)
>
> Envelope, headers, validação do token e novas tentativas.

> [card] [Testar e reenviar](https://docs.gestio.com.br/pages/webhooks/testar-e-reenviar.md)
>
> Payload de exemplo, logs e reenvio.

> [card] [Referência das rotas](https://docs.gestio.com.br/api-reference/webhooks/listar-webhooks.md)
>
> As 12 rotas `/v2/webhooks` na aba Referência, com playground para testar.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.