Webhooks

Instead of polling List escrow transactions or Get customer wallet, let Payluk push updates to you. Payluk sends a signed POST request to your registered callback URL on two separate streams:

Stream	Prefix	Fires when
Escrow lifecycle	`escrow.*`	An escrow you manage is created or changes status.
Transactions	`payment.*`	Any transaction belonging to one of your merchant customers settles: deposits, withdrawals, transfers, wallet sends, and the escrow legs underneath them.

Both streams share the same envelope, the same signature scheme, and the same callback URL. You choose which ones to act on by reading the event field.

Prerequisites

You must set a callback URL for the environment (test or live) in your dashboard business settings. Without one, nothing is sent. Beyond that, each stream has its own condition:

Escrow events: the escrow carries your merchantId (it was created through the API under your merchant account), and its seller is one of your merchant customers (merchant_user).

Transaction events: the transaction belongs to one of your merchant customers. Transactions on your own merchant account do not fire webhooks.

If a condition is not met, no webhook fires and the underlying operation still succeeds as normal.

Payluk picks the callback URL and signing key by the environment the record belongs to: anything created with a sk_live_ key posts to your live callback URL signed with your live secret; sk_test_ records post to your test callback URL signed with your test secret. Transactions that no API key initiated (money arriving in a customer’s reserved account, for example) take the environment of the deployment they happened on.

Escrow events

The event field is escrow.<status> (lower-cased), plus escrow.created when a new escrow is generated. Every status transition emits one event:

Event	Fires when	Lifecycle
`escrow.created`	A new escrow link is generated	`AWAITING_PAYMENT`
`escrow.pending`	Escrow is created/awaiting funding	`AWAITING_PAYMENT`
`escrow.ongoing`	Buyer funded the escrow; funds held	`OPENED`
`escrow.completed`	Buyer confirmed delivery / final milestone released	`CLOSED`
`escrow.claimed`	Seller claimed funds after the delivery window	`CLOSED`
`escrow.disputed`	A party opened a dispute	`OPENED`
`escrow.investigating`	Dispute is under review	`OPENED`
`escrow.refunded`	Dispute resolved in the buyer’s favour	`CLOSED`
`escrow.split`	Dispute resolved by dividing the held funds between both parties	`CLOSED`

An escrow.split payload carries a split object alongside the usual fields, so you can reconcile both legs without a second call:

{
  "status": "SPLIT",
  "state": "CLOSED",
  "split": { "sellerAmount": 30000, "buyerAmount": 20000, "pool": 50000, "resolvedAt": "1786694400" }
}

See Escrow lifecycle for how these map to state and status.

Multi-quantity links emit events for each escrow independently; the original link and every cloned escrow. Match on data.id, not the paymentToken. See Multi-quantity escrows.

Transaction events

Every transaction a merchant customer makes emits an event when it settles, whichever flow produced it, along with the two payouts Payluk makes into your own merchant wallet. Nothing is sent while a transaction is still pending: a deposit that has not cleared is a question, not an answer. The event field is payment.<transactionType>.<outcome>:

Event	Fires when
`payment.deposit.success`	A customer funded their wallet through hosted checkout, a card charge or a crypto transfer.
`payment.transfer.success`	Money paid into a customer’s reserved bank account was credited to their wallet.
`payment.withdrawal.success`	A payout to a customer’s bank account or crypto address completed.
`payment.wallet_transfer.success`	A wallet-to-wallet send between customers completed.
`payment.escrow.success`	The ledger entry for an escrow funding, alongside the `escrow.*` event for the escrow itself.
`payment.commission.success`	Your share of the escrow fee was paid into your merchant wallet.
`payment.delivery.success`	An `additionalFee` (delivery fee) was paid into your merchant wallet.

Each of these has a .failed counterpart that fires when the transaction reaches a terminal failure, for example payment.withdrawal.failed when a bank declines a payout and the customer’s wallet is made whole again. A .reversed counterpart exists for the rarer case of a settled transaction being unwound.

Funding an escrow settles a transaction and moves the escrow, so you receive two webhooks: payment.escrow.success and escrow.ongoing. They describe the same money from different angles. Pick the stream that matches what you are building (escrow.* to track deals, payment.* to keep a ledger) rather than acting on both.

Read creditType to tell direction without parsing the event name: credit means the customer’s wallet went up, debit means it went down. A wallet-to-wallet send emits one event for each side.

The envelope

Every webhook body, on both streams, has the same three top-level fields:

Field	Description
`event`	The event name, for example `escrow.completed` or `payment.deposit.success`.
`data`	The record the event is about. Its shape depends on the stream.
`timestamp`	ISO-8601 time the webhook was generated.

Escrow payload

The data object mirrors the escrow you get from the API, including status, state, settlementType, milestones, totalQuantity, environment and merchantId. The shape is the same across all escrow.* events.

{
  "event": "escrow.completed",
  "data": {
    "id": "665f1b2c9a1e4d0012ab3c10",
    "amount": 150000,
    "purpose": "MacBook Pro 14\"",
    "description": "Space grey, sealed",
    "whoPays": "both",
    "imageUrl": ["https://cdn.payluk.ng/escrow/abc.png"],
    "fee": 3750,
    "additionalFee": 2500,
    "additionalFeeRefundable": true,
    "paymentToken": "PY_8AB12C9D3045",
    "sellerId": "665f1b2c9a1e4d0012ab3c01",
    "buyerId": "665f1b2c9a1e4d0012ab3c02",
    "paidAt": "1750593600",
    "status": "COMPLETED",
    "state": "CLOSED",
    "logs": [],
    "channel": "API",
    "dispute": null,
    "category": null,
    "completedAt": "2026-06-22T12:00:00.000Z",
    "approvedClaimBy": null,
    "refundedBy": null,
    "paymentId": "665f1b2c9a1e4d0012ab3c99",
    "maxDelivery": 3,
    "deliveryDetails": null,
    "deliveryTimeline": "days",
    "totalQuantity": 1,
    "settlementType": "STANDARD",
    "milestones": null,
    "createdAt": "2026-06-22T10:15:00.000Z",
    "updatedAt": "2026-06-22T12:00:00.000Z",
    "environment": "live",
    "merchantId": 4242
  },
  "timestamp": "2026-06-22T12:00:00.000Z"
}

Transaction payload

The data object describes the settled transaction. The shape is the same across all payment.* events; only the detail object matching the transaction type is populated, and the rest are null.

{
  "event": "payment.withdrawal.success",
  "data": {
    "id": "665f1b2c9a1e4d0012ab3d44",
    "reference": "PLK-WD-8842190",
    "amount": 50000,
    "fee": 100,
    "currency": "NGN",
    "status": "success",
    "transactionType": "withdrawal",
    "creditType": "debit",
    "customerId": "665f1b2c9a1e4d0012ab3c02",
    "withdrawalDetails": {
      "bankCode": "058",
      "accountNumber": "0123456789",
      "accountName": "Ada Obi",
      "bankName": "Guaranty Trust Bank",
      "narration": "Payout"
    },
    "walletDetails": null,
    "escrowDetails": null,
    "blockchainDetails": null,
    "createdAt": "2026-06-22T12:00:00.000Z",
    "updatedAt": "2026-06-22T12:00:04.000Z",
    "environment": "live",
    "merchantId": 4242
  },
  "timestamp": "2026-06-22T12:00:04.000Z"
}

Field	Description
`id`	Payluk’s id for the transaction.
`reference`	The transaction reference. Unique, and the right key to de-duplicate on.
`amount`	Amount in naira (or the token unit for a crypto transaction).
`fee`	Payluk’s fee, charged on top of `amount` for a debit and deducted from it for a credit.
`currency`	Currency code, `NGN` unless stated otherwise.
`status`	`success`, `failed` or `reversed`. Matches the last segment of `event`.
`transactionType`	`deposit`, `withdrawal`, `transfer`, `wallet_transfer`, `escrow`, `commission` or `delivery`.
`creditType`	`credit` if the customer’s wallet went up, `debit` if it went down.
`customerId`	The merchant customer the transaction belongs to. On a `commission` or `delivery` payout this is your own merchant account.
`withdrawalDetails`	Beneficiary bank account, on a withdrawal.
`walletDetails`	Counterparty phone and name, on a wallet-to-wallet send.
`escrowDetails`	The `escrowId` this leg belongs to, on an escrow, commission or delivery transaction.
`blockchainDetails`	Network, transaction hash, addresses and confirmations, on a crypto transaction.
`environment`	`live` or `test`. Tells you which secret verifies the signature.
`merchantId`	Your merchant id.

The payload does not name the bank or processor that moved the money. Which rail Payluk settles through changes without notice and is not part of this contract, so nothing in your handler should branch on it. Read transactionType for what happened, and the detail objects for how: withdrawalDetails marks a bank payout, blockchainDetails a crypto one.

Verify the signature

Each request carries an x-payluk-signature header: an HMAC-SHA512 of the raw JSON body, keyed with your environment’s secret key. Always verify it before trusting a payload. This is identical on both streams.

Headers

Content-Type: application/json
User-Agent: Payluk-Webhook/1.0
x-payluk-signature: 9f86d081…   # hex HMAC-SHA512 of the body

import crypto from "crypto";
import express from "express";

const app = express();

// Capture the raw body so the signature matches byte-for-byte.
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; },
}));

app.post("/webhooks/payluk", (req, res) => {
  const secret = process.env.PAYLUK_SECRET_KEY; // sk_live_… or sk_test_…
  const expected = crypto
    .createHmac("sha512", secret)
    .update(req.rawBody)
    .digest("hex");

  const received = req.headers["x-payluk-signature"];

  const valid =
    received &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));

  if (!valid) return res.status(401).send("Invalid signature");

  const { event, data } = req.body;

  if (event.startsWith("payment.")) {
    // …credit your own ledger using data.reference …
  } else {
    // …update the deal using data.status …
  }

  res.sendStatus(200); // acknowledge quickly
});

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/payluk")
def payluk_webhook():
    secret = os.environ["PAYLUK_SECRET_KEY"].encode()
    expected = hmac.new(secret, request.get_data(), hashlib.sha512).hexdigest()
    received = request.headers.get("x-payluk-signature", "")

    if not hmac.compare_digest(expected, received):
        abort(401)

    payload = request.get_json()

    if payload["event"].startswith("payment."):
        ...  # handle a settled transaction
    else:
        ...  # handle an escrow update

    return "", 200

Sign against the exact raw bytes of the request body. If you re-serialize the parsed JSON, key ordering or spacing may differ and the signature won’t match.

Delivery & retries

Behaviour	Detail
Method	`POST` with a JSON body.
Headers	`Content-Type: application/json`, `User-Agent: Payluk-Webhook/1.0`, `x-payluk-signature`.
Timeout	Payluk waits up to 10 seconds for your response.
Retries	Failed attempts are retried up to 3 times with exponential backoff.
Delivery	Best-effort: webhook failures are logged but never block or roll back the operation that caused them. A deposit still credits your customer’s wallet if your endpoint is down.

Acknowledge fast with a 2xx, then do heavy work asynchronously. If you need state that may have arrived out of order, re-fetch: escrows with Verify payment token using the paymentToken, and balances with Get customer wallet using customerId.

Best practices

Always verify the signature

Treat any request with a missing or mismatched x-payluk-signature as untrusted and reject it with 401. Use a constant-time comparison.

Be idempotent

The same event may be delivered more than once (a retry after a slow 2xx). De-duplicate on data.reference for transaction events, and on data.id + event for escrow events, so reprocessing is a no-op.

Ignore events you don't handle

New event names are added over time, and both streams arrive at the same endpoint. Switch on the event field and return 2xx for anything you do not recognise rather than failing the request.

Don't assume order

Events are sent as state changes happen and may arrive out of order under retries. Trust data.status / data.state as the source of truth rather than the sequence of events.

Never treat a webhook as the balance

A transaction event tells you money moved, not what the wallet now holds. If you display a balance, read it from Get customer wallet.

Separate test and live endpoints

Configure distinct callback URLs and verify each with its matching secret (sk_test_ vs sk_live_). The data.environment field tells you which one a payload belongs to.

Get started

Build with AI

The merchant journey

Core concepts

Guides

Reference

Prerequisites

Escrow events

Transaction events

The envelope

Escrow payload

Transaction payload

Verify the signature

Delivery & retries

Best practices

​Prerequisites

​Escrow events

​Transaction events

​The envelope

​Escrow payload

​Transaction payload

​Verify the signature

​Delivery & retries

​Best practices

Prerequisites

Escrow events

Transaction events

The envelope

Escrow payload

Transaction payload

Verify the signature

Delivery & retries

Best practices