> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphagateway.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurar webhooks

> Cadastro do endpoint, eventos disponíveis e assinatura HMAC.

## Como configurar

1. Acesse a página de **Integração** no painel (ou use as rotas de **Webhooks - Endpoints**, com uma API Key de escopo `WEBHOOKS`)
2. Crie um **Endpoint de Webhook** informando a URL pública do seu servidor e selecionando os eventos que deseja receber
3. Copie a **credencial** exibida na criação (mostrada apenas uma vez) — ela é usada para validar a assinatura HMAC
4. Seu servidor deve responder com um status **2xx** (ex.: 200) para confirmar o recebimento. Redirecionamento (3xx) não é seguido e conta como falha: cadastre a URL final
5. Em caso de falha, o sistema realiza novas tentativas de reenvio com backoff exponencial

> Você pode cadastrar vários endpoints. Cada um recebe apenas os eventos que assina e possui sua própria credencial. Um mesmo evento é entregue a todos os endpoints que o assinam.

## Eventos disponíveis

Ao criar ou atualizar um endpoint, assine pelo **valor** (coluna 1). O payload enviado identifica o evento pelo campo `event` (coluna 4) junto com o `status`; o nome legível (coluna 2) aparece só na lista de eventos e nas entregas.

| Valor para assinar | Nome | Quando é disparado | `event` no payload |
| - | - | - | - |
| `PIX_IN_PAYED` | `pix_in.paid` | Cobrança PIX paga | `PIX_IN_UPDATE` (`status` `PAYED`) |
| `PIX_IN_REFUNDED` | `pix_in.refunded` | Cada devolução de uma cobrança PIX ao pagador: parcial (`PARTIALLY_REFUNDED`) ou a que completa o valor (`REFUNDED`) | `PIX_IN_UPDATE` |
| `PIX_OUT_ANALYSIS` | `pix_out.analysis` | Saque solicitado (em análise) | `PIX_OUT_UPDATE` (`status` `ANALYSIS`) |
| `PIX_OUT_PAID` | `pix_out.paid` | Saque confirmado | `PIX_OUT_UPDATE` (`status` `PAID`) |
| `PIX_OUT_REJECTED` | `pix_out.rejected` | Saque rejeitado | `PIX_OUT_UPDATE` (`status` `REJECTED`) |
| `PIX_OUT_ERROR` | `pix_out.error` | Erro no processamento do saque | `PIX_OUT_UPDATE` (`status` `ERROR`) |
| `PIX_OUT_REFUNDED` | `pix_out.refunded` | Cada devolução de um saque pelo recebedor ou pelo banco dele: parcial (`PARTIALLY_REFUNDED`) ou a que completa o valor (`REFUNDED`) | `PIX_OUT_UPDATE` |
| `CHECKOUT_PAID` | `checkout.paid` | Checkout / link de pagamento pago | `CHECKOUT_UPDATE` |
| `CHECKOUT_CANCELED` | `checkout.canceled` | Checkout cancelado | `CHECKOUT_UPDATE` |
| `CHECKOUT_REJECTED` | `checkout.rejected` | Pagamento com cartão recusado | `CHECKOUT_UPDATE` |
| `CHECKOUT_REFUNDED` | `checkout.refunded` | Pagamento com cartão estornado | `CHECKOUT_UPDATE` |
| `BOLETO_CREATED` | `boleto.created` | Boleto gerado | `BOLETO_UPDATE` |
| `BOLETO_PAID` | `boleto.paid` | Boleto pago | `BOLETO_UPDATE` |
| `BOLETO_CANCELED` | `boleto.canceled` | Boleto cancelado / baixado | `BOLETO_UPDATE` |
| `BOLETO_REFUNDED` | `boleto.refunded` | Boleto estornado após pagamento | `BOLETO_UPDATE` |
| `INVOICE_INSTALLMENT_PAID` | `invoice.installment_paid` | Parcela de fatura paga (ainda há parcelas em aberto) | `INVOICE_INSTALLMENT_PAID` |
| `INVOICE_FULLY_PAID` | `invoice.fully_paid` | Fatura totalmente paga (última parcela quitada) | `INVOICE_FULLY_PAID` |
| `INVOICE_INSTALLMENT_OVERDUE` | `invoice.installment_overdue` | Parcela de fatura vencida (passou da data de vencimento sem pagamento) | `INVOICE_INSTALLMENT_OVERDUE` |
| `INVOICE_INSTALLMENT_CHARGE_FAILED` | `invoice.installment_charge_failed` | Cobrança automática da parcela no cartão falhou | `INVOICE_INSTALLMENT_CHARGE_FAILED` |
| `INFRACTION_OPENED` | `infraction.opened` | Infração (MED PIX) aberta — saldo bloqueado | `INFRACTION_UPDATE` |
| `INFRACTION_RESOLVED` | `infraction.resolved` | Infração (MED PIX) resolvida — saldo liberado ou debitado | `INFRACTION_UPDATE` |

## Segurança — Assinatura HMAC

Toda requisição de webhook inclui o header `Alpha-Signature` para você verificar a autenticidade e a integridade do payload:

```
Alpha-Signature: t=1700000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

* `t` — timestamp Unix (segundos) de quando a notificação foi assinada
* `v1` — HMAC-SHA256, em hexadecimal, da string `{t}.{corpo_bruto_da_requisição}` usando a **credencial do endpoint** como chave

Para validar: recalcule o HMAC-SHA256 de `{t}.{corpo_bruto}` com a credencial do endpoint e compare com `v1` usando comparação de tempo constante. Rejeite se o timestamp `t` estiver fora de uma janela de tolerância (ex: 300 segundos).

> Use o **corpo bruto (raw)** da requisição na verificação, não o JSON re-serializado.

> Compatibilidade: integrações que usavam a configuração antiga (header `X-Webhook-Secret`) continuam funcionando — esse header ainda é enviado quando há uma credencial configurada. O `Alpha-Signature` é adicional e recomendado.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.