> 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.md).

# Webhooks

Receba o resultado de cada operação FGTS em tempo real, sem precisar de polling. A cada resultado de operação, o GTFgts envia uma requisição **HTTP POST** para as URLs cadastradas na sua subscription de webhook.

Esta seção documenta o **contrato de entrega** (*outbound*) — ou seja, **o que o originator recebe**. O cadastro/gerenciamento da subscription (CRUD) é feito pela API REST do ingress, descrita em [Configuração via API](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/configuracao-via-api.md) e na [API Reference](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/criar-cadastro-webhook.md).

***

## Como funciona

Quando uma operação FGTS é concluída (averbação, manutenção de garantia, cancelamento de reserva, consulta de saldo, consulta de valor reservado ou consulta de protocolos), a plataforma envia um `POST` para cada URL cadastrada na subscription do originator.

O fluxo:

1. O originator submete uma operação FGTS e recebe `202 Accepted` com um `requestId`
2. A plataforma processa a operação junto à Caixa de forma assíncrona
3. Ao concluir a operação, a plataforma identifica a subscription de webhook do originator
4. Uma requisição `POST` com o corpo do envelope é enviada para cada URL cadastrada
5. Em caso de falha, a entrega é retentada com **back-off exponencial** (entrega *at-least-once*)

{% hint style="info" %}
Os webhooks são enviados **server-to-server**. Seu endpoint precisa estar acessível publicamente via HTTPS. Um header estático `{authKey}: {authValue}` — definido por você na subscription — autentica cada chamada de entrega.
{% endhint %}

***

## O envelope, em resumo

Toda notificação é enviada como `POST` com `Content-Type: application/json`. O corpo é sempre um **envelope** com três campos: `source`, `eventType` e `data`.

```http
POST https://originator.example.com/callbacks/fgts
Content-Type: application/json
X-Webhook-Token: s3cr3t-t0k3n-v4lue

{
  "source": "ENDORSEMENT",
  "eventType": "ENDORSEMENT_FAILED",
  "data": {
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "reserveIdentifier": "orig-123:res-1",
    "status": "FAILED",
    "source": "CAIXA_CALL",
    "error": {
      "code": "ENDORSEMENT_DENIED",
      "message": "Endorsement denied by Caixa",
      "originalErrors": [
        {
          "provider": "CAIXA",
          "code": "14",
          "description": "Averbacao negada — saldo insuficiente",
          "httpStatus": 422,
          "requestIdentifier": "orig-123:res-1",
          "occurredAt": "2026-06-15T10:00:03Z"
        }
      ]
    }
  }
}
```

* **source** — categoria da operação que originou o evento (`BALANCE_QUERY`, `ENDORSEMENT`, `MAINTAIN_GUARANTEE`, `CANCEL_RESERVE`, `QUERY_RESERVED_VALUE`, `LIST_PROTOCOLS_BY_ID`; e `CONTRACT` para os eventos da saga de formalização de contrato — ver [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md))
* **eventType** — tipo do evento (ex.: `ENDORSEMENT_COMPLETED`, `ENDORSEMENT_FAILED`, `ENDORSEMENT_NEEDS_VERIFICATION`); use-o para rotear o tratamento
* **data** — payload do resultado (`requestId`, `status`, `source` e, conforme o caso, `reserveIdentifier`, `protocolNumber`, `result` ou `error`)

O catálogo de eventos está em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md); a estrutura completa de cada campo e os payloads de cada evento estão em [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

{% hint style="info" %}
Use **`data.requestId`** como **chave de idempotência**: é o identificador de correlação que casa a notificação com a submissão original e permite deduplicar reentregas (a entrega é *at-least-once*). Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).
{% endhint %}

***

## Nesta seção

| Página                                                                                                          | O que cobre                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md)                                | Catálogo de `source` e `eventType` e o agrupamento por desfecho (`*_COMPLETED`/`*_FAILED`/`*_NEEDS_VERIFICATION`/`*_UNDER_REVIEW`/`NO_BALANCE`). |
| [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md)                              | Estrutura completa do `data`, `OperationError`/`originalErrors[]`, mapeamento `eventType → result` e exemplos JSON de cada evento.               |
| [Configuração via API](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/configuracao-via-api.md)      | Como cadastrar e gerenciar a subscription: URLs e header `authKey`/`authValue`.                                                                  |
| [Segurança e Exemplos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/seguranca-e-exemplos.md)      | Modelo de autenticação por header estático, idempotência por `requestId` e exemplos de receptores.                                               |
| [Retry e Garantias de Entrega](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/retry-e-garantias.md) | Semântica `2xx`/`4xx`/`3xx`–`5xx`, back-off exponencial e *at-least-once*.                                                                       |

***

## Contrato de entrega (OpenAPI)

O contrato completo da entrega — envelope, schemas `WebhookEnvelope` / `WebhookData` / `OperationError` / `OriginalError` e exemplos — está disponível em formato OpenAPI:

{% file src="/files/GPUK6EysPAyT5TXeDdEd" %}
Contrato de entrega de webhook do GTFgts — o que o originator recebe a cada resultado de operação.
{% endfile %}

{% hint style="info" %}
Este spec descreve **apenas a entrega** (o que o originator recebe): ele tem um bloco `webhooks:`, **não** endpoints REST. Os endpoints de CRUD da subscription pertencem ao contrato do ingress — ver [Configuração via API](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/configuracao-via-api.md).
{% endhint %}

***

## Collection Postman

Para validar o seu receptor, importe a collection com payloads de exemplo de **todos** os eventos de webhook — incluindo os `CONTRACT_*` da saga de formalização:

{% file src="/files/7z2BSLdDWJHwOLgnprij" %}
Exemplos de payload de cada evento de webhook do GTFgts. Configure `webhook_url` (o seu endpoint), `auth_header_key` e `auth_header_value`, e dispare cada evento para testar o seu receptor.
{% endfile %}
