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

# Getting Started

> Set up webhooks to receive real-time notifications about payments, subscriptions, and customer events.

Webhooks notify your application when events occur in PayNext—payments settle, subscriptions renew, customers update. No polling required.

## Webhooks are the source of truth

Webhooks are delivered **server-to-server**, so they don't depend on the customer's browser surviving the checkout round-trip. Drive fulfillment, entitlement, and billing records from webhook events—**not** from the SDK's [`onCheckoutComplete`](/sdk-reference/web-sdk/customization/behavior) callback, which runs in the browser as a UX signal only and isn't guaranteed to fire (the customer can close or background the tab or lose connection, on any payment method, and asynchronous methods can settle slightly later).

Use these [payment and subscription events](/webhooks/introduction/event-types#payment-events) to trigger business logic:

| Event                                                                | What it means                           | What to do                                                            |
| -------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------- |
| `payment_v2.created`                                                 | A payment exists (initially `PENDING`). | Record the payment; wait for the outcome.                             |
| `payment_v2.settled`                                                 | The payment succeeded.                  | Treat as success—fulfill the order. Fires exactly once.               |
| `payment_v2.authorized` / `payment_v2.settling`                      | The payment is in progress.             | Provision optimistically if you choose to.                            |
| `payment_v2.declined` / `payment_v2.failed` / `payment_v2.cancelled` | The payment did not succeed.            | Treat as failure.                                                     |
| `subscription_v2.created`                                            | The subscription is active.             | The cleanest trigger to provision access for a subscription purchase. |

<Note>
  Keep `onCheckoutComplete` for immediate UX only—showing a success or pending screen right after checkout. Because webhooks are delivered server-to-server, driving fulfillment from them removes the closed-tab / lost-connection failure mode entirely.
</Note>

## Set Up a Webhook

<Steps>
  <Step title="Create your endpoint">
    Set up an HTTPS endpoint in your application to receive POST requests with JSON payloads (e.g., `https://api.yourapp.com/webhooks/paynext`).
  </Step>

  <Step title="Register in Dashboard">
    Go to **Dashboard → Developers → Webhooks**, click **Add Endpoint**, and enter your URL.
  </Step>

  <Step title="Select events">
    Choose which event types to receive (e.g., `payment_v2.settled`, `subscription_v2.cancelled`), or subscribe to all events. New endpoints default to the v2 taxonomy—see [Versioning](/webhooks/introduction/versioning).
  </Step>

  <Step title="Save">
    Click **Create** to activate your webhook.
  </Step>
</Steps>

## Monitor Delivery

Each endpoint displays delivery health and statistics:

| Metric               | Description                                                 |
| :------------------- | :---------------------------------------------------------- |
| **Delivery Stats**   | Success rate and volume over time                           |
| **Message Attempts** | Individual delivery attempts with status (Succeeded/Failed) |
| **Logs**             | Detailed request/response logs for debugging                |

Filter message attempts by **All**, **Succeeded**, or **Failed** to troubleshoot issues.

## Verify Signatures

PayNext signs every webhook so you can verify the request originated from us. Always validate signatures before processing events.

### Get your signing secret

1. Go to **Dashboard → Developers → Webhooks**
2. Select your endpoint
3. Copy the **Signing Secret** (format: `whsec_...`)

### Verify the signature

PayNext delivers webhooks through Svix. Pass the **raw request body** (not parsed JSON) and headers to the Svix SDK for verification.

See the Svix documentation for implementation:

* [Platform-specific examples](https://docs.svix.com/receiving/verifying-payloads/how) — Ready-to-use code for Node.js, Python, Go, Ruby, and more
* [Manual verification guide](https://docs.svix.com/receiving/verifying-payloads/how-manual) — HMAC validation without the SDK

## Retries

PayNext automatically retries failed webhook deliveries with exponential backoff:

| Attempt | Delay       |
| :------ | :---------- |
| 1       | Immediately |
| 2       | 5 seconds   |
| 3       | 5 minutes   |
| 4       | 30 minutes  |
| 5       | 2 hours     |
| 6       | 5 hours     |
| 7       | 10 hours    |
| 8       | 10 hours    |

Your endpoint must return `2xx` status to acknowledge receipt. After all attempts fail, the endpoint may be disabled.

<Note>
  If your endpoint consistently fails, check the **Logs** tab for error details. Common issues include SSL certificate errors, timeouts, and non-2xx responses.
</Note>

## Advanced Endpoints

Beyond standard webhooks, PayNext supports alternative delivery methods for specific use cases:

| Endpoint Type            | Use Case                                                 |
| :----------------------- | :------------------------------------------------------- |
| **Polling Endpoint**     | Pull events on your schedule instead of receiving pushes |
| **FIFO Endpoint**        | Guaranteed ordering for event processing                 |
| **Amazon S3**            | Archive events to S3 for compliance or analytics         |
| **Azure Blob Storage**   | Archive events to Azure storage                          |
| **Google Cloud Storage** | Archive events to GCS                                    |
| **OpenTelemetry**        | Stream events to observability platforms                 |

Contact support to enable advanced endpoint types for your account.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook not receiving events">
    * Verify your endpoint URL is publicly accessible
    * Check that the endpoint is **Active** in the Dashboard
    * Ensure your endpoint returns `2xx` status
    * Review delivery logs for error details
  </Accordion>

  <Accordion title="Signature verification failing">
    * Confirm you're using the correct signing secret
    * Pass the raw request body (not parsed JSON) to verification
    * Check that webhook headers are being forwarded correctly
  </Accordion>

  <Accordion title="Events arriving out of order">
    * Use event timestamps to determine correct sequence
    * Implement idempotency using event IDs
    * Consider FIFO endpoints for ordered delivery
  </Accordion>

  <Accordion title="Duplicate deliveries">
    * Each event has a stable `id` that is reused across delivery retries
    * Store processed event IDs and skip any you've already handled
    * See [Versioning → Idempotency](/webhooks/introduction/versioning#idempotency)
  </Accordion>
</AccordionGroup>