# Guide to NextPay Webhooks: Features and Best Practices

[NextPay](https://nextpay.world) 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](https://github.com/hookdeck/webhook-skills/tree/main/skills/nextpay-webhooks/examples) 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_intent.succeeded` 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_intent.succeeded` | Payment received and settled | Fulfil the order via `payload.external_id` |
| `v2.payment_intent.canceled` | A payment intent was cancelled | Release reserved stock |
| `v2.payment_instrument.used` | A single-use Funding Method instrument was used | Mark the instrument consumed |
| `v2.payment_instrument.payment_received` | An incoming Funding Method payment arrived | Show a pending payment |
| `v2.payment_instrument.payment_settled` | That incoming payment cleared | Credit the customer |
| `payout_request.creation_failed` | A payout request failed to create | Alert and retry |
| `payout_request.queued` | A payout request is queued for settlement | Progress display |
| `payout_request.queue_failed` | 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_entity.verification_status_changed` | 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:

```bash
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](/docs/cli) forwards the source to your machine:

```bash
npx hookdeck-cli listen 3000 nextpay --path /webhooks/nextpay

```

Create and pay a payment intent in the sandbox to send a `v2.payment_intent.succeeded`.

## 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:

```javascript
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:

```javascript
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](/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 `5xx` for anything temporary, and `2xx` for 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](/docs/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-id` header, which stays the same across retries.

**How Hookdeck Can Help:** A Hookdeck [transformation](/docs/transformations) 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_intent.succeeded` arrives.

### Credit on settlement, not receipt

`v2.payment_instrument.payment_received` says money is on its way; `payment_settled` says it has cleared. Credit customers on the second.

### Treat payout failures as reconciliation work

`payout_request.creation_failed`, `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](/webhooks/guides/implement-webhook-idempotency) 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](https://hookdeck.com) normalises, stores and retries NextPay events so a payment is never lost to a deploy. [Create a Hookdeck account for free](https://dashboard.hookdeck.com/signup).