Guide to NextPay Webhooks: Features and Best Practices
NextPay runs NextAPI, a Philippine payments API. Businesses use it to collect money through QRPH, cards and payment intents, to send payouts, and to run wallets for the merchants on their platforms. Collections and payouts settle through the banking system at its own pace, so NextAPI's webhooks tell you when a payment settles, a payout is delivered or fails, a deposit is confirmed or a merchant's verification status changes.
What are NextPay webhooks?
NextPay webhooks are registered through the API, one URL per webhook, each with a list of events. Delivery and signing are handled by Svix, which NextPay names in its verification guide.
| Aspect | Value |
|---|---|
| Method | POST, JSON body |
| Signature headers | svix-id, svix-timestamp, svix-signature (Standard Webhooks) |
| Success | Any 2xx within 30 seconds |
| Retries | 5xx and timeouts are retried with exponential backoff; 4xx is not retried |
| Delivery | At-least-once. Deduplicate on svix-id (the docs say the event id). Ordering is not stated |
The skill's reference applications handle all 16 documented events.
NextPay webhook features
| Feature | Details |
|---|---|
| Configuration | API only, POST /v2/webhooks with Basic auth |
| Filtering | events list per webhook |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | svix-signature |
| Secret | whsec_<base64>, returned once on create |
| Body | JSON, two shapes |
| Event routing | Body field type, or event for v2.* events |
| Retries | 5 attempts over about 2.5 hours. 4xx isn't retried |
| Testing | NextAPI sandbox account |
| Source IPs | Not published |
Events and payloads
The body shape depends on the event's category:
| Field | Meaning |
|---|---|
event | Event name for v2.* events |
type | Event name for payout and platform events |
payload | The resource for v2.* events |
data | The resource for payout and platform events |
So a v2.payment_ arrives as { "event": ..., "payload": ... }, and a payout.failed as { "type": ..., "data": ... }. Read whichever name field is present before routing.
| Event | Triggered When | Common Use Cases |
|---|---|---|
v2.payment_ | Payment received and settled | Fulfil the order via payload.external_id |
v2.payment_ | A payment intent was cancelled | Release reserved stock |
v2.payment_ | A single-use Funding Method instrument was used | Mark the instrument consumed |
v2.payment_ | An incoming Funding Method payment arrived | Show a pending payment |
v2.payment_ | That incoming payment cleared | Credit the customer |
payout_ | A payout request failed to create | Alert and retry |
payout_request.queued | A payout request is queued for settlement | Progress display |
payout_ | A payout request failed to queue | Alert and retry |
payout_request.processed | A payout request is fully processed | Mark the batch done |
payout.succeeded | An individual payout was delivered | Confirm to the payee |
payout.failed | An individual payout failed | Notify and reconcile |
payout.processed | An individual payout finished processing | Progress display |
payout.processing_failed | An individual payout failed during processing | Notify and reconcile |
deposit.confirmed | An inbound deposit was confirmed on an account | Credit the ledger |
direct_transfer.received | An account received a direct transfer | Credit the ledger |
legal_ | A merchant KYC/compliance status changed | Unlock or restrict features |
NextPay's docs don't claim the list is complete. Their two example bodies elide their IDs and neither is tied to a specific event, so log real sandbox deliveries before writing parsers for payload and data.
Setting up NextPay webhooks
You need a NextAPI client ID and secret, which authenticate webhook management with Basic auth. Register the URL and the events you want:
curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
-X POST "https://api.partners.nextpay.world/v2/webhooks" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/webhooks/nextpay",
"events": ["v2.payment_intent.succeeded", "payout_request.processed", "payout.failed"]
}'
The response includes the webhook id and its secret. NextPay shows the secret only in this response, so store it in NEXTPAY_WEBHOOK_SECRET straight away, whsec_ prefix included. There's no challenge or validation request: the endpoint only has to accept POST and return 2xx.
To point an existing webhook at a different URL, such as a Hookdeck source, send PATCH /v2/webhooks/{id} with {"url": "https://..."}.
To receive NextPay events through Hookdeck, create a source with the NextPay type and paste the secret. For local work, the Hookdeck CLI forwards the source to your machine:
npx hookdeck-cli listen 3000 nextpay --path /webhooks/nextpay
Create and pay a payment intent in the sandbox to send a v2.payment_.
Securing NextPay webhooks
NextPay's verification guide gives the construction: HMAC-SHA256 over {svix-id}.{svix-timestamp}.{rawBody}, keyed with the base64-decoded secret after whsec_, compared against each v1, entry in the space-separated svix-signature header. This function also accepts webhook-* header names, matching the Hookdeck source:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['svix-id'] ? 'svix' : 'webhook';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
NextPay points to the Svix libraries, which reject timestamps more than five minutes off. That suits a direct receiver. Hookdeck applies no tolerance and resends the original svix-timestamp on retries and replays, so behind Hookdeck those libraries would reject genuine events. The function above has no age check.
Money movements must not be applied twice, so the receiver records each message by svix-id and leaves ledger updates to a worker:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
// paymentsInbox.insert(messageId, name, body) stores the message once and resolves when durable.
function createNextPayReceiver(paymentsInbox) {
const app = express();
app.post('/webhooks/nextpay', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.NEXTPAY_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const body = parseJsonObject(req.body);
if (!body) return res.sendStatus(400); // signed, but not a JSON object
const name = body.event || body.type; // v2.* events use `event`, others `type`
try {
await paymentsInbox.insert(req.headers['svix-id'] || req.headers['webhook-id'], name, body);
} catch {
return res.sendStatus(503); // 5xx is retried; 4xx would not be
}
return res.sendStatus(200);
});
return app;
}
If NextPay sends to a Hookdeck source with a bad signature, Hookdeck still returns 200, records failed verification and holds the request back.
Make NextPay webhooks production-ready. Hookdeck Event Gateway verifies every payment and payout event, keeps it past NextPay's 2.5-hour retry window, and routes collections and payouts to separate services.
NextPay webhook limitations and pain points
4xx responses are final
The Problem: A payout failure that your app rejected with 400 during a bad deploy is never sent again.
Why It Happens: NextPay retries 5xx and timeouts, but not 4xx.
Workarounds:
- Return
5xxfor anything temporary, and2xxfor events you deliberately ignore. - Reconcile payouts and payment intents through the API after incidents.
How Hookdeck Can Help: With Hookdeck in front, NextPay always gets 200, and Hookdeck retries your service according to your own rules.
Retries end after about 2.5 hours
The Problem: A longer outage loses payment events.
Why It Happens: NextPay makes five attempts: immediately, then 1 minute, 5 minutes, 30 minutes and 2 hours later.
Workarounds:
- Keep the receiver small and highly available, and backfill through the API.
How Hookdeck Can Help: Hookdeck stores each event as it arrives, then retries and lets you replay it whenever your service is ready.
The secret is shown once
The Problem: The webhook works, but nobody can verify it because the secret wasn't saved.
Why It Happens: The secret only appears in the POST /v2/webhooks response.
Workarounds:
- Register webhooks from a script that writes the secret straight into your secrets store.
- If it's lost, check NextPay's API reference for how to recreate the webhook.
How Hookdeck Can Help: Saving the secret on the Hookdeck source puts it in one place, so your services don't each need a copy.
Two shapes and no top-level ID
The Problem: A parser written for payout events crashes on a payment intent, and there's no obvious event ID to deduplicate on.
Why It Happens: v2.* events use event and payload, others use type and data. NextPay says to deduplicate on the event id, but its examples show no top-level id.
Workarounds:
- Normalise both shapes in one place in your code, and deduplicate on the
svix-idheader, which stays the same across retries.
How Hookdeck Can Help: A Hookdeck transformation can normalise both shapes into one before they reach your service.
Best practices
Fulfil from payload.external_id
Set your own order reference as external_id on payment intents, and use it to find the order when v2.payment_ arrives.
Credit on settlement, not receipt
v2.payment_ says money is on its way; payment_settled says it has cleared. Credit customers on the second.
Treat payout failures as reconciliation work
payout_, queue_failed, payout.failed and payout.processing_failed each mean money didn't move as planned. Route them to whoever reconciles payouts.
Store svix-id with the ledger change
Write the ID in the same transaction as the ledger entry. The webhook idempotency guide explains why that matters.
Conclusion
NextPay's webhooks follow payments and payouts on a Philippine payments platform, with Svix signing and API-managed registration. Handle both body shapes, and save the secret when you create the webhook because it isn't shown again.
Hookdeck Event Gateway normalises, stores and retries NextPay events so a payment is never lost to a deploy. Create a Hookdeck account for free.