> 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/seguranca-e-exemplos.md).

# Segurança e Exemplos

***

## Autenticação

Cada requisição de webhook inclui um **header estático** de autenticação, definido por você na subscription: o nome é o `authKey` e o valor é o `authValue` (ver [Configuração via API](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/configuracao-via-api.md)). O serviço envia esse header — e só ele — em **todas** as entregas.

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

{% hint style="warning" %}
A autenticação é por **header estático**, **não** HMAC. O `authValue` é um segredo compartilhado:

* **Mantenha-o secreto** — trate-o como qualquer credencial e mantenha o `authValue` fora dos seus logs.
* **Valide-o no seu endpoint** — compare o header recebido com o valor esperado antes de processar o payload e rejeite com `401`/`403` se não bater.
  {% endhint %}

### Recomendações

* **HTTPS obrigatório** — configure seus endpoints exclusivamente com HTTPS (as `webhookUrls` precisam iniciar com `https://`).
* **Valide o header** — sempre verifique o `authKey`/`authValue` antes de processar o payload.
* **Responda rápido** — confirme com `2xx` o quanto antes e processe o payload de forma assíncrona se necessário.
* **Idempotência** — deduplique pelo par (`data.requestId`, `eventType`), pois a entrega é *at-least-once* (ver [Retry e Garantias de Entrega](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/retry-e-garantias.md)).

***

## Idempotência por `requestId` e `eventType`

A entrega é **at-least-once**: o mesmo evento pode chegar **mais de uma vez** em caso de falha de rede, timeout ou resposta não-`2xx`. Use o par **(`data.requestId`, `eventType`)** como chave de idempotência. O `requestId` sozinho não basta: a mesma operação emite mais de um evento — `CANCEL_RESERVE_UNDER_REVIEW` e depois `CANCEL_RESERVE_FAILED`, por exemplo — e deduplicar só por ele descarta o desfecho final.

Padrão recomendado para o receptor:

1. **Validar** o header de autenticação (`authKey`/`authValue`); rejeitar com `401` se inválido.
2. **Deduplicar** por (`data.requestId`, `eventType`): se você já processou esse par, responda `2xx` e ignore.
3. **Confirmar** com `2xx` imediatamente (ack), antes de qualquer processamento pesado.
4. **Processar** o evento de forma assíncrona, roteando por `eventType`.

Ver também [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).

***

## Exemplos de implementação

O corpo é um envelope com `source`, `eventType` e `data`. Use `data` como payload do evento e `eventType` para rotear.

### Recebendo webhooks (Node.js / Express)

```javascript
const express = require('express');
const app = express();

app.use(express.json());

const processed = new Set(); // troque por um store persistente (Redis/DB)

app.post('/callbacks/fgts', (req, res) => {
  // 1. valida o header estático (authKey/authValue da subscription)
  const token = req.headers['x-webhook-token'];
  if (token !== process.env.WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const { source, eventType, data } = req.body;

  // 2. deduplica por requestId + eventType (entrega at-least-once)
  const dedupKey = `${data.requestId}:${eventType}`;
  if (processed.has(dedupKey)) {
    return res.status(200).json({ received: true, duplicate: true });
  }
  processed.add(dedupKey);

  // 3. ack imediato, 4. processamento assíncrono roteado por eventType
  processWebhookAsync(eventType, source, data);

  res.status(200).json({ received: true });
});

app.listen(3000);
```

### Recebendo webhooks (Python / Flask)

```python
from flask import Flask, request, jsonify
import os

app = Flask(__name__)
processed = set()  # troque por um store persistente (Redis/DB)


@app.route('/callbacks/fgts', methods=['POST'])
def webhook():
    # 1. valida o header estático (authKey/authValue da subscription)
    token = request.headers.get('X-Webhook-Token')
    if token != os.environ.get('WEBHOOK_SECRET'):
        return jsonify({'error': 'Unauthorized'}), 401

    body = request.get_json()
    source = body.get('source')
    event_type = body.get('eventType')
    data = body.get('data')

    # 2. deduplica por requestId + eventType (entrega at-least-once)
    dedup_key = (data.get('requestId'), event_type)
    if dedup_key in processed:
        return jsonify({'received': True, 'duplicate': True}), 200
    processed.add(dedup_key)

    # 3. ack imediato, 4. processamento assíncrono roteado por event_type
    process_webhook_async(event_type, source, data)

    return jsonify({'received': True}), 200
```

### Recebendo webhooks (Java / Spring Boot)

```java
@RestController
@RequestMapping("/callbacks/fgts")
public class WebhookController {

    @Value("${webhook.secret}")
    private String webhookSecret;

    @PostMapping
    public ResponseEntity<Map<String, Boolean>> handleWebhook(
            @RequestHeader("X-Webhook-Token") String token,
            @RequestBody Map<String, Object> envelope) {

        // 1. valida o header estático (authKey/authValue da subscription)
        if (!webhookSecret.equals(token)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
        }

        String source = (String) envelope.get("source");
        String eventType = (String) envelope.get("eventType");
        Map<String, Object> data = (Map<String, Object>) envelope.get("data");
        String dedupKey = data.get("requestId") + ":" + eventType;

        // 2. deduplica por requestId + eventType (entrega at-least-once)
        if (alreadyProcessed(dedupKey)) {
            return ResponseEntity.ok(Map.of("received", true));
        }
        markProcessed(dedupKey);

        // 3. ack imediato, 4. processamento assíncrono roteado por eventType
        processWebhookAsync(eventType, source, data);

        return ResponseEntity.ok(Map.of("received", true));
    }
}
```

***

## Eventos `*_NEEDS_VERIFICATION` / `status = EXPIRED`

Os eventos `ENDORSEMENT_NEEDS_VERIFICATION`, `MAINTAIN_GUARANTEE_NEEDS_VERIFICATION` e `CANCEL_RESERVE_NEEDS_VERIFICATION` (com `data.status = EXPIRED`) indicam que a operação **expirou aguardando a resposta da Caixa** — o desfecho real ainda é **incerto**. Nesses casos, **não assuma sucesso nem falha**: o evento não traz `result`, e o `error` traz apenas `code = EXPIRED_TTL`, que marca a expiração e não é veredito da Caixa.

{% hint style="warning" %}
Ao receber um `*_NEEDS_VERIFICATION` / `status = EXPIRED`, **verifique** o status real por polling antes de tomar qualquer decisão de negócio: [`GET /api/v1/fgts/operations/{requestId}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md). Use o `data.requestId` recebido no evento.
{% endhint %}

Confirmado por polling que a operação de fato não teve desfecho, uma **averbação** nesse estado é [retentável](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) — não é preciso abrir chamado nem submeter reserva nova.

***

## Checklist de integração

* [ ] Endpoint HTTPS configurado e acessível publicamente
* [ ] Validação do header estático (`authKey`/`authValue`) implementada
* [ ] `authValue` mantido em segredo e fora dos logs
* [ ] Resposta `2xx` retornada rapidamente (ack)
* [ ] Deduplicação por `data.requestId` implementada (entrega *at-least-once*)
* [ ] Processamento assíncrono do payload, roteado por `eventType`
* [ ] Verificação por polling para `*_NEEDS_VERIFICATION` / `EXPIRED`
* [ ] Monitoramento e alertas configurados para falhas no endpoint
