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

# Gerenciar pela API

> Cadastre, consulte, altere, exclua, ative, desative e rotacione o token dos webhooks pelas rotas /v2/webhooks.

Os webhooks são gerenciados pelas rotas `/v2/webhooks` da API de Clientes. Todas exigem o token de acesso da API no header `Authorization`, e a empresa é sempre a do token: não é possível consultar ou alterar webhooks de outra empresa.

```bash theme={null}
Authorization: Bearer SEU_TOKEN_DE_ACESSO
```

> [card] [Gere um token em /v2/autenticar](https://docs.gestio.com.br/pages/autenticacao/reference.md)
>
> Envie `email` e `password` do usuário de integração para receber o `accessToken`.

| Método | Rota | Descrição |
| - | - | - |
| `GET` | `/v2/webhooks/eventos` | Lista os eventos que podem ser assinados |
| `GET` | `/v2/webhooks` | Lista os webhooks da empresa |
| `GET` | `/v2/webhooks/{idEndpoint}` | Consulta um webhook |
| `POST` | `/v2/webhooks` | Cadastra um webhook |
| `PUT` | `/v2/webhooks/{idEndpoint}` | Altera nome, URL e eventos |
| `PATCH` | `/v2/webhooks/{idEndpoint}/situacao` | Ativa ou desativa o webhook |
| `DELETE` | `/v2/webhooks/{idEndpoint}` | Exclui o webhook, os eventos e os logs |
| `POST` | `/v2/webhooks/{idEndpoint}/rotacionar-token` | Gera um novo token |
| `POST` | `/v2/webhooks/{idEndpoint}/testar` | Envia um payload de exemplo de cada evento assinado |
| `GET` | `/v2/webhooks/{idEndpoint}/logs` | Lista os logs do webhook (paginado) |
| `GET` | `/v2/webhooks/logs/{idLog}` | Consulta um log, com o envelope enviado |
| `POST` | `/v2/webhooks/logs/{idLog}/reenviar` | Reenvia um log |

> [!NOTE]
>
> As rotas de teste, logs e reenvio estão detalhadas em [Testar e reenviar](https://docs.gestio.com.br/pages/webhooks/testar-e-reenviar.md).

## Envelope de resposta

As rotas seguem o mesmo envelope das demais rotas `/v2`: sucesso traz `success: true` e `data`; falha de negócio traz HTTP `400` com `success: false` e `errors`.

```json Sucesso theme={null}
{
  "success": true,
  "data": { }
}
```

```json Falha (400) theme={null}
{
  "success": false,
  "errors": [
    {
      "key": null,
      "value": "A URL do webhook deve ser uma URL https válida.",
      "dateOccurred": "2026-11-06T14:00:00"
    }
  ]
}
```

| Código | Quando acontece |
| - | - |
| `200` | Sucesso |
| `400` | Falha de validação ou de regra de negócio (inclusive id inexistente nas rotas de **escrita**) |
| `401` | Token ausente, inválido ou expirado |
| `404` | `GET /v2/webhooks/{idEndpoint}` e `GET /v2/webhooks/logs/{idLog}` com id inexistente ou de outra empresa |
| `429` | Limite de requisições por minuto da API de Clientes excedido |

> [!NOTE]
>
> Nas rotas de **leitura** de um registro, um id inexistente ou de outra empresa responde `404`. Nas rotas de **escrita** (alterar, excluir, testar, reenviar…), o mesmo caso responde `400` com a mensagem `Endpoint não encontrado.` — em nenhum dos casos a API revela que o id existe em outra empresa.

***

## Cadastrar um webhook

`POST /v2/webhooks`

**descricao** `string` *required*

Nome para identificar o webhook. Máximo de 100 caracteres.

**url** `string` *required*

URL que receberá os eventos. Máximo de 2000 caracteres. Veja as [regras da URL](#regras-da-url).

**eventos** `string[]` *required*

Códigos dos eventos assinados (ao menos um, sem repetição). Veja o [catálogo de eventos](https://docs.gestio.com.br/pages/webhooks/eventos.md).

```bash cURL theme={null}
curl -X POST "https://api.gestio.com.br/v2/webhooks" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
  -H "Content-Type: application/json" \
  -d '{
    "descricao": "ERP Matriz - pedidos de compra",
    "url": "https://integracao.suaempresa.com.br/webhooks/gestio",
    "eventos": ["compras.pedido-de-compra.processado"]
  }'
```

```json Corpo theme={null}
{
  "descricao": "ERP Matriz - pedidos de compra",
  "url": "https://integracao.suaempresa.com.br/webhooks/gestio",
  "eventos": ["compras.pedido-de-compra.processado"]
}
```

**Resposta (`200`):**

```json theme={null}
{
  "success": true,
  "data": {
    "idEndpoint": "8d1f6c2a-3b4e-4a5f-9e6d-7c8b9a0f1e2d",
    "descricao": "ERP Matriz - pedidos de compra",
    "url": "https://integracao.suaempresa.com.br/webhooks/gestio",
    "eventos": ["compras.pedido-de-compra.processado"],
    "ativo": true,
    "tokenMascarado": "****0f1e",
    "falhasConsecutivas": 0,
    "desativadoAutomaticamenteEm": null,
    "criadoEm": "2026-11-06T14:00:00",
    "atualizadoEm": null,
    "token": "gwhtok_0000000000000000000000000000000000000000000000000000000000000f1e"
  }
}
```

> [!WARNING]
>
> O token tem o formato `gwhtok_` seguido de 64 caracteres hexadecimais. O campo `token` completo só é devolvido **nesta resposta** e na rotação do token. Guarde-o em um cofre de segredos do seu sistema: nas consultas seguintes ele aparece apenas mascarado (`tokenMascarado`, com os 4 últimos caracteres).

> [!TIP]
>
> É possível cadastrar mais de um webhook com a mesma URL; cada um terá o seu próprio token.

### Regras da URL

* Deve usar **`https`**.
* Não pode conter usuário ou senha (`https://usuario:senha@...`).
* Deve apontar para um endereço **público** na internet: `localhost`, `127.0.0.1`, IPs de rede privada (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), loopback, link-local e domínios terminados em `.localhost`, `.local`, `.internal` e `.lan` são recusados.
* O host precisa ser resolvido por DNS no momento do cadastro.
* A validação do endereço público é refeita **a cada envio**: se o host passar a resolver para um endereço privado, o envio falha definitivamente.

Para receber webhooks no seu ambiente local durante o desenvolvimento, use um túnel HTTPS público (por exemplo, um serviço de túnel ou de captura de webhooks).

***

## Listar e consultar

`GET /v2/webhooks` devolve em `data` a lista de webhooks da empresa e `GET /v2/webhooks/{idEndpoint}` devolve um webhook, nos mesmos campos da resposta de cadastro, **sem** o campo `token`.

**idEndpoint** `string (uuid)`

Identificador do webhook.

**descricao** `string`

Nome do webhook.

**url** `string`

URL atual do webhook.

**eventos** `string[]`

Códigos dos eventos assinados.

**ativo** `boolean`

Se o webhook está recebendo eventos.

**tokenMascarado** `string`

Token mascarado, com os 4 últimos caracteres.

**falhasConsecutivas** `integer`

Tentativas de envio com falha seguidas. Volta a `0` após um sucesso.

**desativadoAutomaticamenteEm** `string (date-time) | null`

Preenchido quando o webhook foi desativado automaticamente por falhas.

**criadoEm** `string (date-time)`

Data de cadastro.

**atualizadoEm** `string (date-time) | null`

Data da última alteração.

Um `idEndpoint` inexistente ou de outra empresa responde `404` com `{ "success": false, "data": null }`.

***

## Alterar

`PUT /v2/webhooks/{idEndpoint}` recebe o mesmo corpo do cadastro (`descricao`, `url` e `eventos`) e aplica as mesmas validações. A resposta traz o webhook atualizado, **sem** o campo `token`.

> [!NOTE]
>
> A nova URL vale apenas para os logs criados depois da alteração. Logs anteriores, inclusive quando reenviados, continuam indo para a URL gravada no momento em que foram criados.

***

## Ativar e desativar

`PATCH /v2/webhooks/{idEndpoint}/situacao`

```json theme={null}
{ "ativo": false }
```

* Webhooks **inativos** não recebem novos eventos: nenhum log é criado para eles.
* Logs que ainda estavam pendentes quando o webhook foi desativado são encerrados como `Falha` com o erro "Endpoint desativado".
* Ao **reativar**, o contador `falhasConsecutivas` volta a `0` e `desativadoAutomaticamenteEm` é limpo.
* Um log **não** pode ser reenviado enquanto o webhook estiver inativo.

### Desativação automática

Se o webhook acumular **20 tentativas de envio com falha seguidas**, o Gestio o desativa automaticamente e preenche `desativadoAutomaticamenteEm`. Corrija o problema no seu sistema e reative o webhook pela rota acima. Um envio com sucesso zera o contador.

> [!NOTE]
>
> O contador é por **tentativa**, não por log: um único log que esgote as 6 tentativas soma 6 falhas consecutivas. Logs de **teste** não entram nessa conta.

***

## Excluir

`DELETE /v2/webhooks/{idEndpoint}`

Exclui definitivamente o webhook, os eventos assinados e **todo o histórico de logs** dele. Como o webhook deixou de existir, a resposta não o devolve: `data` é apenas `true`.

```json theme={null}
{ "success": true, "data": true }
```

Depois da exclusão, o webhook some de `GET /v2/webhooks` e tanto ele quanto os logs dele respondem `404`.

> [!WARNING]
>
> A exclusão é **definitiva** e apaga o histórico de logs junto. Para apenas parar de receber eventos preservando o histórico, use `PATCH /v2/webhooks/{idEndpoint}/situacao` com `{ "ativo": false }`.

> [!NOTE]
>
> Se houver envios desse webhook ainda na fila no momento da exclusão, eles são simplesmente descartados, sem erro.

***

## Rotacionar o token

`POST /v2/webhooks/{idEndpoint}/rotacionar-token` gera um novo token e o devolve uma única vez no campo `token`, no mesmo formato da resposta de cadastro.

A partir da rotação, **todos os logs novos e os reenvios** usam o novo token, inclusive logs antigos que forem reenviados. Atualize o token no seu sistema logo após a rotação.

> [!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.

***

## Mensagens de erro

| Mensagem | Causa |
| - | - |
| A descrição do webhook deve ser informada. | `descricao` vazia |
| A descrição do webhook deve ter no máximo 100 caracteres. | `descricao` muito longa |
| A URL do webhook deve ser informada. | `url` vazia |
| A URL do webhook deve ter no máximo 2000 caracteres. | `url` muito longa |
| A URL do webhook deve ser uma URL https válida. | URL inválida ou sem `https` |
| A URL do webhook não pode conter usuário ou senha. | URL com credenciais |
| A URL do webhook aponta para um endereço não permitido. | Host local, loopback, rede privada ou domínio interno |
| Não foi possível resolver o host da URL do webhook. | Domínio inexistente |
| Informe pelo menos um evento do webhook. | `eventos` vazio |
| Os eventos do webhook não podem se repetir. | Evento duplicado na lista |
| O evento '…' não existe ou não pode ser inscrito. | Código fora do catálogo |
| Endpoint não encontrado. | `idEndpoint` inexistente ou de outra empresa, em rota de escrita |
| Entrega de webhook não encontrada. (mensagem literal da API) | `idLog` inexistente ou de outra empresa, em rota de escrita |
| O webhook não tem eventos assinados. Assine ao menos um evento para testá-lo. | Teste de um webhook sem eventos |
| Não há exemplo de payload para o evento '…'. | Teste de um evento ainda sem exemplo |


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