Understanding Webhooks
Webhooks are automated HTTP callbacks that NextAPI sends to your server when events occur. Instead of polling the API for status updates, you receive instant notifications.
How Webhooks Work
Event occurs → NextAPI creates webhook payload → HTTP POST to your endpoint → You acknowledge
NextAPI signs each delivery so you can verify it came from us, not a malicious third party.
Webhook Payload Structure
Every webhook delivery includes:
{
"id": "evt_abc123",
"created": 1705312200,
"type": "payout_request.completed",
"data": {
"id": "pr_xyz789",
"amount": 10000,
"currency": "PHP",
"status": "completed",
"account_id": "acc_456",
"processed_at": "2024-01-15T10:30:00Z"
}
}
| Field | Description |
|---|---|
id | Unique event ID. Use for deduplication. |
created | Unix timestamp of when the event occurred |
type | Event type (e.g., payout_request.completed) |
data | The resource that changed, with its current state |
Event Types
Payout Events
| Event | Description |
|---|---|
payout_request.initiated | Payout request created |
payout_request.pending | Payout queued for processing |
payout_request.processing | Payout being processed by provider |
payout_request.completed | Payout successfully delivered |
payout_request.failed | Payout failed |
payout_request.cancelled | Payout cancelled |
payout_request.reversed | Completed payout reversed |
Payment Events
| Event | Description |
|---|---|
payment_intent.created | Payment intent created |
payment_intent.paid | Payment successfully received |
payment_intent.expired | Payment intent expired |
payment_intent.cancelled | Payment intent cancelled |
Delivery and Retries
NextAPI retries failed deliveries with exponential backoff:
| Attempt | Delay | Cumulative Wait |
|---|---|---|
| 1 | Immediate | — |
| 2 | 1 minute | 1 minute |
| 3 | 5 minutes | 6 minutes |
| 4 | 30 minutes | 36 minutes |
| 5 | 2 hours | ~2.5 hours |
Response expectations:
- 2xx — Success. Webhook processed, no retry.
- 4xx — Client error. No retry (fix your endpoint).
- 5xx — Server error. Retry scheduled.
Your endpoint must respond within 30 seconds or the delivery is considered failed.
Idempotency
Webhook events may be delivered more than once. Always use the id field to deduplicate:
- Store processed event IDs
- Before processing, check if the event ID was already handled
- Skip duplicates
This prevents double-processing (e.g., crediting an account twice for the same payment).
Security
Webhook payloads are signed with your webhook secret. Always verify the signature before processing. The signature is included in the x-nextpay-signature header as an HMAC-SHA256 digest.
For implementation details, see Setup Webhooks.
Related
- Setup Webhooks — implementation guide with code
- The Lifecycle of a Payout — events that trigger payout webhooks
- Wallet Structure — understand the accounts that emit events