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.settled, subscription.cancelled), or subscribe to all events.4
Save
Click Create to activate your webhook.
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 |
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
- Go to Dashboard → Developers → Webhooks
- Select your endpoint
- 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 — Ready-to-use code for Node.js, Python, Go, Ruby, and more
- Manual verification guide — 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 |
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:| 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 |
Troubleshooting
Webhook not receiving events
Webhook not receiving events
- Verify your endpoint URL is publicly accessible
- Check that the endpoint is Active in the Dashboard
- Ensure your endpoint returns
2xxstatus - Review delivery logs for error details
Signature verification failing
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
Events arriving out of order
Events arriving out of order
- Use event timestamps to determine correct sequence
- Implement idempotency using event IDs
- Consider FIFO endpoints for ordered delivery