# Avisos de saída

Em vez de perguntar de tempos a tempos se a cobrança caiu, diga-nos para onde
avisar. Configura-se no painel, em **Integração**.

O endereço tem de ser `https`. Um aviso de pagamento em texto simples atravessa
a rede legível por quem estiver no caminho, e leva o valor, o estado e a sua
referência.

## O que chega

```json
{
  "id": "evt_...",
  "type": "payment.paid",
  "data": {
    "id": "...",
    "status": "PAID",
    "previous_status": "PENDING",
    "amount_minor": 8900,
    "currency": "BRL",
    "external_reference": "PEDIDO-1234",
    "occurred_at": "2026-08-24T12:00:00-03:00"
  }
}
```

É **deliberadamente pequeno**, e não leva nada do cartão. O que vai aqui chega
para o seu sistema decidir; o resto busca-se pela API, autenticado. Um webhook é
uma campainha, não um armazém: quanto menos leva, menos há para vazar no dia em
que o seu endereço for parar ao sítio errado.

## Confira a assinatura. Sempre.

Cada aviso leva:

```
X-TrionPay-Signature: t=1756900000,v1=<hmac-sha256>
X-TrionPay-Event-Id: <id do evento>
```

O `v1` é `HMAC-SHA256` de `"{t}.{corpo cru}"` com o seu segredo.

```php
$partes = [];
foreach (explode(',', $request->header('X-TrionPay-Signature')) as $p) {
    [$k, $v] = array_pad(explode('=', trim($p), 2), 2, '');
    $partes[$k] = $v;
}

$corpo = $request->getContent();   // o corpo cru, sem reserializar
$esperado = hash_hmac('sha256', $partes['t'] . '.' . $corpo, $seuSegredo);

if (! hash_equals($esperado, $partes['v1'] ?? '')) {
    abort(400);                     // não veio de nós
}

if (abs(time() - (int) $partes['t']) > 300) {
    abort(400);                     // velho de mais: pode ser repetição
}
```

**Sem esta verificação, qualquer pessoa que descubra o seu endereço pode enviar
"pagamento aprovado" e ver a mercadoria sair.** O endereço não é segredo — está
no seu código e nos logs do seu servidor.

O **carimbo entra na assinatura** de propósito: assinar só o corpo deixaria a
porta aberta a quem grave um aviso válido e o reenvie depois. Recuse o que tiver
mais de cinco minutos.

## Responda depressa, e trate a repetição

Responda `2xx` assim que receber. Temos dez segundos de paciência — se o seu
servidor demorar mais a dizer "recebi", tentamos outra vez mais tarde.

Se falhar, repetimos com intervalos crescentes: 30s, 2min, 10min, 1h, 6h. Ao fim
disso desistimos, **e a tentativa fica registada** — se ligar a perguntar por um
aviso que nunca chegou, conseguimos dizer-lhe o que aconteceu.

**O mesmo `id` pode chegar duas vezes.** A rede não garante entrega exactamente
uma vez, e nós preferimos avisar a mais do que a menos. Trate o mesmo `id` como
a mesma notícia — guardar os ids já processados é o suficiente.

## Se o segredo vazar

Gere outro no painel. O anterior deixa de valer no momento em que o novo nasce,
portanto tenha o novo no lugar antes de trocar.