Skip to main content
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 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 to trigger business logic:
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.

​
Set Up a Webhook

1

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).
2

Register in Dashboard

Go to Dashboard → Developers → Webhooks, click Add Endpoint, and enter your URL.
3

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.
4

Save

Click Create to activate your webhook.

​
Monitor Delivery

Each endpoint displays delivery health and statistics: 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:

​
Retries

PayNext automatically retries failed webhook deliveries with exponential backoff: Your endpoint must return 2xx status to acknowledge receipt. After all attempts fail, the endpoint may be disabled.
If your endpoint consistently fails, check the Logs tab for error details. Common issues include SSL certificate errors, timeouts, and non-2xx responses.

​
Advanced Endpoints

Beyond standard webhooks, PayNext supports alternative delivery methods for specific use cases: Contact support to enable advanced endpoint types for your account.

​
Troubleshooting

  • 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
  • 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
  • Use event timestamps to determine correct sequence
  • Implement idempotency using event IDs
  • Consider FIFO endpoints for ordered delivery
  • 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