# Webhooks de Pagamento

Este módulo unifica a entrada de webhooks dos provedores `mercadopago`, `pagbank`, `pagarme` e `asaas` (além de `itau` para Pix) em um único conjunto de rotas. A validação de segurança usa HMAC-SHA256 do corpo JSON com um segredo compartilhado por tenant.

## Endpoints

- `GET /api/payments/webhooks/{mercadopago|pagbank|pagarme|asaas|itau}?tenant=<id>` — Healthcheck simples (retorna `{"ok":true}`)
- `POST /api/payments/webhooks/{mercadopago|pagbank|pagarme|asaas|itau}` — Recebe eventos. Cabeçalhos:
  - `x-tenant-id: <id do tenant>`
  - `x-idempotency-key: <id único do evento>` (opcional; se ausente, usa hash do corpo)
  - `x-signature: <hmac sha256 do JSON com o segredo>`

## Segredos por Tenant

- Os segredos são armazenados por tenant na tabela `payment_provider_settings` com criptografia AES-GCM via `Crypto`.
- Salve os segredos pela UI em `Financeiro > Bancos > Integrações de Pagamento`. A UI chama `POST /api/payments/settings/{provider}` (protegid0 por JWT + permissão `financeiro.update`).
  - Em ambientes de desenvolvimento/teste, quando o DB não está populado, o webhook aceita um fallback via ambiente para alguns provedores:
    - `MP_WEBHOOK_SECRET` para Mercado Pago
    - `PAGBANK_WEBHOOK_SECRET` para PagBank
    - `ASAAS_WEBHOOK_SECRET` para Asaas
  - Outros provedores seguem o mesmo fluxo pela UI.

## Assinatura (HMAC)

1. Serialize o corpo exatamente como será enviado (JSON sem escapes extras).
2. Calcule `HMAC-SHA256` usando o segredo do tenant.
3. Envie o valor em `x-signature`.

Exemplo com `curl` (Mercado Pago):

```bash
export MP_WEBHOOK_SECRET='segredo-dev-123'
body='{"type":"payment","data":{"id":"mp_evt_1001","status":"approved","amount":123.45}}'
sig=$(php -r "echo hash_hmac('sha256', '$body', getenv('MP_WEBHOOK_SECRET'));")
curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-tenant-id: default' \
  -H "x-signature: $sig" \
  -d "$body" \
  http://localhost:8001/api/payments/webhooks/mercadopago
```

## Idempotência

- O controlador marca eventos processados usando `x-idempotency-key` (ou hash do corpo) para evitar reprocessamentos.

## Notas de Segurança

- Em produção, configure `CERT_STORE_KEY` para habilitar a criptografia de segredos no DB.
- Evite usar o fallback de ambiente em produção; prefira armazenar os segredos por tenant pela UI.