> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/configuracao-via-api.md).

# Configuração via API

O originator cadastra, consulta, atualiza e remove sua **subscription** de webhook pela API REST do ingress, usando o token JWT de origem. A subscription define **para onde** entregar (`webhookUrls`) e **como autenticar** (`authKey`/`authValue`). O originator recebe **todos** os tipos de evento automaticamente — não há seleção de eventos.

**Base path:** `/api/v1/webhooks`

Cada originator possui no máximo **uma** subscription (relação 1:1). Para atualizar, use `PUT`. Ao concluir cada operação, a plataforma envia um `POST` para cada URL cadastrada, com retry e back-off exponencial em caso de falha — ver [Retry e Garantias de Entrega](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/retry-e-garantias.md).

{% hint style="info" %}
O campo `authValue` é **write-only**: aceito no `POST`/`PUT`, mas **nunca** retornado em leituras (`GET`). É persistido cifrado/como secret.
{% endhint %}

***

## Campos da subscription

| Campo         | Tipo                  | Obrigatório    | Descrição                                                                                                                                                                          |
| ------------- | --------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webhookUrls` | `array<string>`       | Sim            | Lista de URLs HTTPS de entrega. Mínimo 1, máximo 20. Todas devem iniciar com `https://` (máx. 500 caracteres cada). O mesmo evento é entregue para **todas** as URLs configuradas. |
| `authKey`     | `string`              | Sim            | Nome do header HTTP de autenticação enviado em cada entrega (ex.: `X-Webhook-Token`). 1–100 caracteres.                                                                            |
| `authValue`   | `string` (write-only) | Sim            | Valor secreto do header de autenticação. Aceito no `POST`/`PUT`, **nunca** retornado em `GET`. 1–500 caracteres. Definido por você e mantido em segredo.                           |
| `active`      | `boolean`             | Sim (no `PUT`) | Indica se a subscription está ativa e receberá entregas. Enviado no `PUT` e retornado nas leituras.                                                                                |

{% hint style="info" %}
A resposta da API (`201` na criação, `200` na consulta) inclui campos gerados pelo servidor que não fazem parte do corpo de entrada: `id` (identificador interno da subscription) e `createdDate` (timestamp ISO-8601 da criação) são **read-only** — nunca enviados nas requisições. O campo `active` é retornado nas leituras e nasce `true` na criação: **não** o envie no `POST` (a subscription é criada sempre ativa), mas **envie-o no `PUT`** para ativar ou desativar a subscription.
{% endhint %}

{% hint style="info" %}
O originator recebe **todos** os tipos de evento automaticamente — não há seleção nem filtro de eventos na subscription. Veja o catálogo completo de `eventType` entregues em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).
{% endhint %}

***

## Endpoints (CRUD)

O ciclo completo de gerenciamento da subscription está na API Reference:

| Operação      | Endpoint                  | Referência                                                                                                                                      |
| ------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Criar**     | `POST /api/v1/webhooks`   | [Criar cadastro de webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/criar-cadastro-webhook.md)         |
| **Consultar** | `GET /api/v1/webhooks`    | [Obter cadastro de webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/obter-cadastro-webhook.md)         |
| **Atualizar** | `PUT /api/v1/webhooks`    | [Atualizar cadastro de webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/atualizar-cadastro-webhook.md) |
| **Remover**   | `DELETE /api/v1/webhooks` | [Remover cadastro de webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/remover-cadastro-webhook.md)     |

***

## Exemplo — criar subscription

```http
POST /api/v1/webhooks
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "webhookUrls": [
    "https://originator.example.com/callbacks/fgts"
  ],
  "authKey": "X-Webhook-Token",
  "authValue": "s3cr3t-t0k3n-v4lue"
}
```

A resposta `201` ecoa a subscription **sem** o `authValue` (write-only):

```json
{
  "id": 42,
  "webhookUrls": [
    "https://originator.example.com/callbacks/fgts"
  ],
  "authKey": "X-Webhook-Token",
  "active": true,
  "createdDate": "2026-06-14T10:00:00Z"
}
```

***

## authKey e authValue

| Campo         | Descrição                                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **authKey**   | Nome do header HTTP que o GTFgts envia em cada `POST` para as suas URLs (ex.: `X-Webhook-Token`, `Authorization`).         |
| **authValue** | Valor desse header. Configurado por você e enviado em todas as chamadas de entrega. Write-only — não é retornado em `GET`. |

Valide sempre o header no seu endpoint antes de processar o payload. Detalhes do modelo de autenticação e exemplos de receptores em [Segurança e Exemplos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/seguranca-e-exemplos.md).
