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

# Eventos

Catálogo dos eventos de webhook do GTFgts: **quais** `source` e `eventType` existem e como se agrupam por desfecho. Para a estrutura do corpo entregue (`data`, `result`, `error`) e os exemplos JSON de cada evento, ver [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

Todos os valores são extraídos do contrato de entrega ([gtfgts-webhook.openapi.yaml](https://github.com/giro-tech/giro-tech-docs/tree/github-to-gitbook/openapi/gtfgts-webhook/gtfgts-webhook.openapi.yaml)).

***

## Formato do envelope

Toda notificação é enviada com o corpo no formato **envelope**, com três campos:

```json
{
  "source": "ENDORSEMENT",
  "eventType": "ENDORSEMENT_FAILED",
  "data": { ... }
}
```

* **source** — categoria da operação que produziu o evento.
* **eventType** — tipo do evento (combinação de operação + status + conteúdo do resultado). Use-o para rotear o tratamento e para filtrar apenas os eventos que interessam.
* **data** — payload do resultado da operação. Sua estrutura está documentada em [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

***

## Valores de `source`

O `source` no envelope identifica a **categoria da operação** que originou o evento.

| `source`                | Operação                                                                                                                                                                                                                                  |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BALANCE_QUERY`         | Consulta de saldo FGTS.                                                                                                                                                                                                                   |
| `ENDORSEMENT`           | Averbação.                                                                                                                                                                                                                                |
| `MAINTAIN_GUARANTEE`    | Manutenção de garantia.                                                                                                                                                                                                                   |
| `CANCEL_RESERVE`        | Cancelamento de reserva.                                                                                                                                                                                                                  |
| `QUERY_RESERVED_VALUE`  | Consulta de valor reservado.                                                                                                                                                                                                              |
| `LIST_PROTOCOLS_BY_ID`  | Consulta de protocolos por reserva.                                                                                                                                                                                                       |
| `QUERY_PROTOCOL_STATUS` | Consulta de status por protocolo.                                                                                                                                                                                                         |
| `CONTRACT`              | Saga de **formalização de contrato** (CCB). Eventos de *milestone* produzidos pelo serviço de formalização — **não** derivam de uma operação FGTS-Caixa. Ver [Eventos de formalização de contrato](#eventos-de-formalizacao-de-contrato). |

***

## Valores de `eventType`

O `eventType` é derivado da combinação **operação + `status` + conteúdo do `result`**. São **28** valores para as operações **FGTS-Caixa**, agrupados por operação. O sufixo indica o desfecho (a saga de formalização de contrato adiciona outros **14** eventos `CONTRACT_*`, com catálogo próprio — ver [Eventos de formalização de contrato](#eventos-de-formalizacao-de-contrato)):

* **`*_COMPLETED`** — operação concluída com sucesso. O payload traz `result` (resultado opaco da operação).
* **`*_FAILED`** — operação negada/com erro. O payload traz `error` (`OperationError`).
* **`*_NEEDS_VERIFICATION`** — a operação expirou sem desfecho (`status = EXPIRED`), ainda na fila da Giro e sem que houvesse veredito da Caixa. **Verifique** por polling antes de assumir um resultado.
* **`*_UNDER_REVIEW`** — evento **intermediário** (não-terminal): a operação foi aceita e entrou em **revisão manual** da Giro. Ocorre no cancelamento de reserva (`CANCEL_RESERVE_UNDER_REVIEW`) e na manutenção de garantia (`MAINTAIN_GUARANTEE_UNDER_REVIEW`). É **sempre** seguido por um evento terminal (`*_COMPLETED` ou `*_FAILED`).
* **`ENDORSEMENT_RETRYING`** — evento **intermediário** (não-terminal): a Caixa respondeu um código transiente à averbação e a Giro **já reagendou** a próxima tentativa. Nada foi decidido, e é **sempre** seguido por um terminal (`ENDORSEMENT_COMPLETED` ou `ENDORSEMENT_FAILED`). Em geral não é preciso agir — a exceção é o código **`7`** em `data.retry.lastProviderError`, que significa autorização pendente do trabalhador no app do FGTS e depende de uma ação dele para converter. Ver [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).
* **`*_CANCELLED`** — a Giro cancelou a operação enquanto ela ainda estava na fila, antes de qualquer chamada à Caixa. Terminal; `error.code = OPERATOR_CANCELLED`. O cancelamento feito por você (`DELETE /api/v1/fgts/operations/{requestId}`) **não** gera este evento. Submeta de novo se ainda precisar.
* **`BALANCE_QUERY_NO_BALANCE`** — consulta de saldo concluída, porém **sem saldo FGTS** disponível.

| Operação                                                                                                                                                  | `eventType`                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Consulta de saldo/margem FGTS                                                                                                                             | `BALANCE_QUERY_COMPLETED`, `BALANCE_QUERY_NO_BALANCE`, `BALANCE_QUERY_FAILED`, `BALANCE_QUERY_CANCELLED`                                                                |
| Averbação                                                                                                                                                 | `ENDORSEMENT_COMPLETED`, `ENDORSEMENT_FAILED`, `ENDORSEMENT_NEEDS_VERIFICATION`, `ENDORSEMENT_RETRYING`, `ENDORSEMENT_CANCELLED`                                        |
| Manutenção de garantia                                                                                                                                    | `MAINTAIN_GUARANTEE_UNDER_REVIEW`, `MAINTAIN_GUARANTEE_COMPLETED`, `MAINTAIN_GUARANTEE_FAILED`, `MAINTAIN_GUARANTEE_NEEDS_VERIFICATION`, `MAINTAIN_GUARANTEE_CANCELLED` |
| Cancelamento de reserva — avulso ou [encerramento de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento.md) | `CANCEL_RESERVE_UNDER_REVIEW`, `CANCEL_RESERVE_COMPLETED`, `CANCEL_RESERVE_FAILED`, `CANCEL_RESERVE_NEEDS_VERIFICATION`, `CANCEL_RESERVE_CANCELLED`                     |
| Consulta de valor reservado                                                                                                                               | `QUERY_RESERVED_VALUE_COMPLETED`, `QUERY_RESERVED_VALUE_FAILED`, `QUERY_RESERVED_VALUE_CANCELLED`                                                                       |
| Consulta de protocolos por reserva                                                                                                                        | `LIST_PROTOCOLS_COMPLETED`, `LIST_PROTOCOLS_FAILED`, `LIST_PROTOCOLS_CANCELLED`                                                                                         |
| Consulta de status por protocolo                                                                                                                          | `QUERY_PROTOCOL_STATUS_COMPLETED`, `QUERY_PROTOCOL_STATUS_FAILED`, `QUERY_PROTOCOL_STATUS_CANCELLED`                                                                    |

***

{% hint style="info" %}
A subscription recebe **todos** os `eventType` automaticamente — não há seleção nem filtro de eventos no cadastro. Ver [Configuração via API](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/configuracao-via-api.md).
{% endhint %}

***

## Agrupamento por desfecho

A regra é direta: **use o `eventType` para saber qual forma de `data` esperar.** A estrutura do `data` é a mesma dentro de cada **grupo de desfecho** (o sufixo do `eventType`), independentemente da operação. Em vez de decorar 28 formatos diferentes, você lida com **sete grupos**:

| Grupo (sufixo do `eventType`) | `status`              | Significado                                                                                                                                                                                                                                                         |
| ----------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `*_COMPLETED`                 | `COMPLETED`           | Operação concluída com sucesso. O resultado vem em `result`.                                                                                                                                                                                                        |
| `BALANCE_QUERY_NO_BALANCE`    | `COMPLETED`           | Consulta de saldo concluída, mas **sem saldo FGTS** disponível. Caso especial do `COMPLETED`.                                                                                                                                                                       |
| `*_FAILED`                    | `FAILED` ou `EXPIRED` | Operação negada/com erro. Não há `result`. Nas **consultas** (`BALANCE_QUERY`, `QUERY_RESERVED_VALUE`), a expiração também é entregue aqui, com `status = EXPIRED`.                                                                                                 |
| `*_NEEDS_VERIFICATION`        | `EXPIRED`             | A operação expirou sem desfecho, ainda na fila da Giro. **Não há `result`**; o `error` traz apenas `code = EXPIRED_TTL`, que marca a expiração e **não** é veredito da Caixa — **verifique** por polling antes de assumir um resultado.                             |
| `*_UNDER_REVIEW`              | `UNDER_REVIEW`        | **Intermediário** (não-terminal): o cancelamento de reserva ou a manutenção de garantia entrou em **revisão manual** da Giro. **Não há `result` nem `error`** — a operação ainda não foi à Caixa. **Sempre** seguido por um terminal (`*_COMPLETED` ou `*_FAILED`). |
| `ENDORSEMENT_RETRYING`        | `RETRYING`            | **Intermediário** (não-terminal): a averbação está em **retentativa automática** da Giro. **Não há `result`**; o `error` traz o código transiente da Caixa que motivou a espera, e `retry` traz o progresso da janela. **Sempre** seguido por um terminal.          |
| `*_CANCELLED`                 | `CANCELLED`           | Terminal: a Giro cancelou a operação na fila. `error.code = OPERATOR_CANCELLED`, sem `result`.                                                                                                                                                                      |

{% hint style="info" %}
**As consultas (`BALANCE_QUERY`, `QUERY_RESERVED_VALUE`) não têm desfecho `*_NEEDS_VERIFICATION`**: quando expiram, são entregues como `*_FAILED` (com `status = EXPIRED` e `error`). As operações que alteram estado na Caixa (averbação, manutenção de garantia, cancelamento de reserva) têm o desfecho `*_NEEDS_VERIFICATION` justamente porque, ao expirar, o resultado real ainda pode ter sido aplicado e precisa ser confirmado.
{% endhint %}

***

## Eventos de formalização de contrato

Os eventos `CONTRACT_*` (todos com `source = CONTRACT`) narram a **saga de formalização de um contrato (CCB)** e são produzidos pelo serviço de formalização — **não** derivam de uma operação FGTS-Caixa nem seguem os grupos de desfecho acima. Cada evento marca um **milestone** do ciclo de vida do contrato.

Diferente dos eventos FGTS, a correlação é feita pelo par **`data.contractNumber`** (número de negócio do contrato, sequencial por originator) + **`data.clientReference`** (id do cliente que você forneceu): um mesmo contrato gera **vários** `requestId` ao longo da saga. Esses eventos são sempre em **inglês** e **não** carregam PII crua (sem CPF em claro). A forma do `data` está em [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md); o mesmo andamento também pode ser consultado por polling em [Consultar contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md).

| `eventType`                           | Quando                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTRACT_RECEIVED`                   | Contrato (CCB) recebido e validado pela saga (ack).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `CONTRACT_ENDORSED`                   | Averbação/reserva confirmada na Caixa.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `CONTRACT_PAYMENT_APPROVAL_REQUIRED`  | Gate de aprovação de pagamento ativo: o contrato aguarda `POST .../payment-approval` antes de prosseguir ao GTBanker.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `CONTRACT_ENDORSEMENT_REJECTED`       | A Caixa recusou a averbação. O motivo vem em `data.error`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `CONTRACT_ENDORSEMENT_RETRYING`       | Averbação em retentativa automática; o contrato segue em `PENDING_ENDORSEMENT`. Não é preciso agir.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `CONTRACT_SENT_TO_GTBANKER`           | Payload e documento enviados ao GTBanker.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `CONTRACT_FORMALIZED`                 | O GTBanker confirmou o recebimento da CCB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `CONTRACT_PAID`                       | Desembolso confirmado. `data.paymentReceiptUrl`, quando presente, é o link do comprovante — trate como credencial (ver [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md)).                                                                                                                                                                                                                                                                                                                                 |
| `CONTRACT_FORMALIZATION_FAILED`       | Falha/recusa no GTBanker. Nem sempre é terminal: o contrato pode seguir retido para nova tentativa — acompanhe o próximo evento.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `CONTRACT_PAYMENT_FAILED`             | Falha no desembolso — **informativo** (em resolução pela Giro). O motivo vem em `data.error`.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `CONTRACT_PAYMENT_REVISION`           | Pagamento em revisão: **reenvie a conta de desembolso** até `data.dueAt` via [`PUT .../disbursement-account`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md). `data.availableActions` diz se só uma conta nova é aceita (`NEW_ACCOUNT`) ou se a mesma conta pode ser reenviada (`RETRY`).                                                                                                                                                                                           |
| `CONTRACT_CANCELLATION_REJECTED`      | Cancelamento pedido via [`DELETE .../contracts/{contractNumber}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) interrompido porque o provedor bancário já pagou a CCB. `data.status = CANCELLATION_REJECTED`, `data.error.code = CONTRACT_ALREADY_DISBURSED`. O contrato segue para `DISBURSED` (`CONTRACT_PAID`). Para desfazer a operação, envie a desistência (`SEVEN_DAYS_REGRET`).                                                                                                  |
| `CONTRACT_CANCELLED`                  | Contrato cancelado. `data.reason.code` diz por quê: `CANCELLED_BY_ORIGINATOR` (pedido via [`DELETE .../contracts/{contractNumber}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md)), `ENDORSEMENT_DENIED_NOT_RETRYABLE` (recusa da Caixa que não adianta retentar — código 52), `ENDORSEMENT_RETRY_WINDOW_EXPIRED` (averbação recusada e não retentada dentro da janela) ou `DISBURSEMENT_REVISION_EXPIRED` (revisão de conta de desembolso expirada sem nova conta; reserva desaverbada). |
| `CONTRACT_DOCUMENT_GENERATED`         | Documento (PDF) do contrato gerado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `CONTRACT_DOCUMENT_GENERATION_FAILED` | A geração da CCB falhou; o contrato fica em `DOCUMENT_GENERATION_FAILED`. Causa em `data.error.message`. Acione o suporte. **Não é terminal**: se a geração for concluída depois (resultado atrasado ou geração refeita pelo suporte), chega `CONTRACT_DOCUMENT_GENERATED` e o contrato volta a `AWAITING_SIGNED_DOCUMENT` — siga o fluxo normal do Modo B.                                                                                                                                                                                 |

{% hint style="info" %}
Os eventos `CONTRACT_*` **não** seguem os sufixos de desfecho (`*_COMPLETED` / `*_FAILED` / `*_NEEDS_VERIFICATION` / `*_UNDER_REVIEW`) das operações FGTS-Caixa, e o `data.status` deles é o **marco** do contrato (`ENDORSED`, `PAID`, `CANCELLED`…), não `COMPLETED`/`FAILED`. Os campos da saga (`contractNumber`, `clientReference` e, na revisão, `dueDate`/`dueAt`/`availableActions`/`reason`) vêm no nível raiz de `data`. Eles não trazem um `result` de operação Caixa; quando há um nó de milestone do serviço de formalização, ele vem em `data.result` (`ContractMilestoneResult` — presente em `CONTRACT_PAYMENT_REVISION`/`CONTRACT_PAYMENT_FAILED`). Ver [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).
{% endhint %}

***

A forma de cada `data` por grupo — a tabela de campos, a seção `error`/`OperationError`/`originalErrors[]`, o mapeamento `eventType → result` e os exemplos JSON na íntegra de cada evento — está em [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).
