> ## 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

> Payment and KYC event notifications via webhooks: payload format, verification, and best practices.

Webhooks let your application receive asynchronous notifications when relevant events happen (for example, a payment settlement or a KYC status change).

<Note>
  Event names and the exact payload format depend on your account configuration. Confirm the available fields in the PagFinance dashboard or with support before going to production.
</Note>

## How it works

<Steps>
  <Step title="Configure the endpoint">
    Register an HTTPS URL of your application to receive the events.
  </Step>

  <Step title="Receive the event">
    PagFinance sends a `POST` request with the event payload to your URL.
  </Step>

  <Step title="Respond quickly">
    Respond `2xx` as fast as possible. Process heavy logic asynchronously.
  </Step>

  <Step title="Handle retries">
    On failure or timeout, the event may be resent. Handle events idempotently.
  </Step>
</Steps>

## Event types

<ResponseField name="payment.created" type="event">
  A payment was created.
</ResponseField>

<ResponseField name="payment.submitted" type="event">
  The payment's on-chain transaction was submitted.
</ResponseField>

<ResponseField name="payment.settled" type="event">
  The payment was settled in local currency (PIX, boleto, or gift card).
</ResponseField>

<ResponseField name="payment.failed" type="event">
  The payment failed or was rejected.
</ResponseField>

<ResponseField name="kyc.updated" type="event">
  The status of a KYC verification changed.
</ResponseField>

## Payload example

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

## Best practices

<CardGroup cols={2}>
  <Card title="Idempotency" icon="arrows-rotate">
    Use the event identifier to avoid duplicate processing on retries.
  </Card>

  <Card title="Verification" icon="shield-check">
    Validate the authenticity of the request (signature or shared secret) before trusting the payload.
  </Card>

  <Card title="Fast response" icon="bolt">
    Respond `2xx` immediately and process in the background.
  </Card>

  <Card title="HTTPS" icon="lock">
    Only expose HTTPS endpoints to receive events.
  </Card>
</CardGroup>

<Warning>
  This section describes the typical behavior of PagFinance webhooks. The exact events and fields must be confirmed against your account's operational documentation.
</Warning>