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

# Segurança e Exemplos

Como autenticar e receber webhooks no seu endpoint.

## Autenticação

Cada requisição traz o header configurado na assinatura: nome em `authKey` (ex.: `Authorization`, `X-Webhook-Secret`, `X-Api-Key`) e valor em `authValue`. Ver [Configuração via API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/configuracao-via-api.md).

```http
POST https://seu-servidor.com/webhook
Authorization: seu-token-secreto
Content-Type: application/json
```

### Recomendações

* **HTTPS obrigatório** nos endpoints.
* **Valide o header** antes de processar o payload. Token inválido: responda `401` (não haverá retry — ver [Retry e Garantias](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/retry-e-garantias.md)).
* **Responda rápido** (< 30 s) e processe o payload de forma assíncrona. Acima de 60 s a entrega falha por timeout e é retentada.
* **Whitelist de IPs**, se possível: solicite o IP de origem do GTPayroll à equipe de integração.

## Exemplos de implementação

O body é o envelope `{ source, eventType, data }`: roteie por `eventType` e use `data` como payload.

### Node.js / Express

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

app.use(express.json());

app.post('/webhook', (req, res) => {
  if (req.headers['authorization'] !== process.env.WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const { eventType, data } = req.body;
  processWebhookAsync(eventType, data);

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

app.listen(3000);
```

### Python / Flask

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

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    if request.headers.get('Authorization') != os.environ.get('WEBHOOK_SECRET'):
        return jsonify({'error': 'Unauthorized'}), 401

    body = request.get_json()
    process_webhook_async(body.get('eventType'), body.get('data'))

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

### Java / Spring Boot

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

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

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

        if (!webhookSecret.equals(token)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
        }

        processWebhookAsync((String) envelope.get("eventType"), envelope.get("data"));

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

Payload completo de cada evento, inclusive `MARGIN_QUERY_COMPLETED` com `alerts` e `legacyLoans`, em [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).

## Troubleshooting

| Problema                    | Causa provável                      | Solução                                                                                                                                                        |
| --------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Webhook não recebido        | Assinatura inativa ou URL incorreta | Confira a assinatura em [Consultar subscription](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/configuracao-via-api.md#consultar-subscription) |
| Erro 401/403                | Token de autenticação incorreto     | Confirme `authKey` e `authValue` da assinatura                                                                                                                 |
| Evento cancelado sem retry  | Seu endpoint retornou 4xx           | Corrija o endpoint para retornar 2xx e solicite reenvio                                                                                                        |
| Eventos duplicados          | Retry após timeout                  | Implemente [idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/retry-e-garantias.md#idempotencia)                                     |
| Timeout na entrega          | Endpoint lento (> 60 s)             | Responda logo e processe de forma assíncrona                                                                                                                   |
| Evento não chega após retry | Limite de 5 tentativas atingido     | Solicite reenvio manual à equipe de suporte                                                                                                                    |

Problema persistente: contate a equipe de integração com o período dos eventos afetados. O status e o número de tentativas de cada entrega estão em [Listar deliveries](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/configuracao-via-api.md#listar-deliveries).

## Checklist de integração

* [ ] Endpoint HTTPS acessível publicamente
* [ ] Validação do header de autenticação
* [ ] Resposta `2xx` rápida (< 30 s) e processamento assíncrono
* [ ] Idempotência contra duplicatas
* [ ] Tratamento de cada `eventType` necessário
* [ ] Monitoramento e alertas para falhas no endpoint
* [ ] Teste end-to-end com a equipe de integração
