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.
Todos os valores são extraídos do contrato de entrega (gtfgts-webhook.openapi.yaml).
Formato do envelope
Toda notificação é enviada com o corpo no formato envelope, com três campos:
{
"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.
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.
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):
*_COMPLETED— operação concluída com sucesso. O payload trazresult(resultado opaco da operação).*_FAILED— operação negada/com erro. O payload trazerror(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 (*_COMPLETEDou*_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_COMPLETEDouENDORSEMENT_FAILED). Em geral não é preciso agir — a exceção é o código7emdata.retry.lastProviderError, que significa autorização pendente do trabalhador no app do FGTS e depende de uma ação dele para converter. Ver Payloads.*_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
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
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.
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; o mesmo andamento também pode ser consultado por polling em Consultar contrato.
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).
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. 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} 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}), 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.
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.
Atualizado