Webhooks allow Payluk to notify your application in real time whenever important escrow-related events occur. Instead of repeatedly polling the API, Payluk sends an HTTP POST request to your configured webhook URL whenever there is a change in the state of an escrow transaction.

Webhooks are commonly used to:

Track escrow lifecycle changes
Update status
Handle dispute resolutions
Reconcile payments and refunds automatically

Once configured, Payluk will deliver webhook events for every relevant escrow action.

Webhook Payload Structure

Each webhook request sent by Payluk contains a JSON payload with the following top-level fields:

status – HTTP-like status code indicating the result of the action
message – Human-readable description of the event
event – The event type (e.g. escrow.updated)
data – The full escrow object related to the event

Sample Webhook Event (`escrow.eventType`)

Below is an example webhook payload sent by Payluk when an escrow is updated, such as during dispute resolution or refund processing:

{
  "status": 200,
  "message": "Dispute resolution submitted successfully",
  "event": "escrow.completed",
  "data": {
    "id": "69494677cb570eeef7628771",
    "amount": 1000,
    "purpose": "Boxes",
    "description": "Watches",
    "whoPays": "buyer",
    "imageUrl": null,
    "fee": 15,
    "paymentToken": "PY_bOffh0Ee2407",
    "paidAt": "1766409928",
    "status": "REFUNDED",
    "state": "CLOSED",
    "logs": ["DISPUTED"],
    "channel": "API",
    "isSeller": false,
    "dispute": [
      {
        "name": "Daniel",
        "profile": null,
        "message": "I no like item wey the seller give me",
        "proofUrl": null,
        "type": "buyer",
        "createdAt": "2025-12-22 14:13:25"
      },
      {
        "name": "Mary",
        "profile": null,
        "message": "i feel this is really unfair to say the item is not okay",
        "proofUrl": null,
        "type": "seller",
        "createdAt": "2025-12-22 14:55:34"
      },
      {
        "name": "KALU",
        "profile": "https://mediacloud.me/media/bWVkaWEvaW1hZ2VzL29wdGltaXplL1pvcG9lVDF1VDhTN0ZjaDlMUmRQMHFycEdWbU04MlBNRTh1bFdhd08uanBn.jpg",
        "message": "funds has been refunded",
        "proofUrl": "https://mediacloud.me/media/bWVkaWEvaW1hZ2VzL29wdGltaXplL3l2aURJdHhKZHFQOHR2Vk9NcWVwaXJVendEeTN1cERqOGxoWGxlbWwuanBn.jpg",
        "type": "customer support",
        "createdAt": "2025-12-22 15:32:31"
      }
    ],
    "paymentDetails": {
      "id": "694946c7cb570eeef762877f",
      "amount": 1015,
      "status": "success",
      "reference": "9364766547485",
      "fee": 15,
      "transactionType": "escrow",
      "currency": "NGN",
      "createdAt": "2025-12-22T13:25:27.501Z"
    },
    "completedAt": "1766417550",
    "deliveryTimeline": "minutes",
    "totalQuantity": 1,
    "createdAt": "2025-12-22T13:24:07.872Z",
    "updatedAt": "2025-12-22T15:32:31.016Z"
  }
}

Webhook Event Mapping

Payluk sends webhook notifications whenever an escrow status changes.

Status Change	Webhook Event
Escrow created	`escrow.created`
Payment completed	`escrow.ongoing`
Funds released	`escrow.completed`
Dispute opened	`escrow.disputed`
Dispute under review	`escrow.investigating`
Funds refunded	`escrow.refunded`

Always verify webhook signatures using x-payluk-signature.