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

# Webhooks

> Notificações de eventos de pagamento e KYC via webhooks: formato do payload, verificação e boas práticas.

Webhooks permitem que sua aplicação receba notificações assíncronas quando eventos relevantes ocorrem (por exemplo, a liquidação de um pagamento ou a mudança de status de um KYC).

<Note>
  Os nomes de eventos e o formato exato do payload dependem da configuração da sua conta. Confirme os campos disponibilizados no painel do PagFinance ou com o suporte antes de ir para produção.
</Note>

## Como funciona

<Steps>
  <Step title="Configurar o endpoint">
    Cadastre uma URL HTTPS da sua aplicação para receber os eventos.
  </Step>

  <Step title="Receber o evento">
    O PagFinance envia uma requisição `POST` com o payload do evento para a sua URL.
  </Step>

  <Step title="Responder rapidamente">
    Responda `2xx` o mais rápido possível. Processe a lógica pesada de forma assíncrona.
  </Step>

  <Step title="Tratar reenvios">
    Em falha ou timeout, o evento pode ser reenviado. Trate os eventos de forma idempotente.
  </Step>
</Steps>

## Tipos de evento

<ResponseField name="payment.created" type="evento">
  Um pagamento foi criado.
</ResponseField>

<ResponseField name="payment.submitted" type="evento">
  A transação on-chain do pagamento foi submetida.
</ResponseField>

<ResponseField name="payment.settled" type="evento">
  O pagamento foi liquidado na moeda local (PIX, boleto ou giftcard).
</ResponseField>

<ResponseField name="payment.failed" type="evento">
  O pagamento falhou ou foi rejeitado.
</ResponseField>

<ResponseField name="kyc.updated" type="evento">
  O status de uma verificação de KYC mudou.
</ResponseField>

## Exemplo de payload

<ResponseExample>
  ```json POST theme={null}
  {
    "event": "payment.settled",
    "data": {
      "paymentId": "pay_123",
      "type": "pix",
      "status": "settled",
      "amount": 150.00,
      "currency": "BRL"
    }
  }
  ```
</ResponseExample>

## Boas práticas

<CardGroup cols={2}>
  <Card title="Idempotência" icon="arrows-rotate">
    Use o identificador do evento para evitar processamento duplicado em reenvios.
  </Card>

  <Card title="Verificação" icon="shield-check">
    Valide a autenticidade da requisição (assinatura ou segredo compartilhado) antes de confiar no payload.
  </Card>

  <Card title="Resposta rápida" icon="bolt">
    Responda `2xx` imediatamente e processe em background.
  </Card>

  <Card title="HTTPS" icon="lock">
    Exponha apenas endpoints HTTPS para receber eventos.
  </Card>
</CardGroup>

<Warning>
  Esta seção descreve o comportamento típico de webhooks do PagFinance. Os eventos e campos exatos devem ser confirmados com a documentação operacional da sua conta.
</Warning>