Webhook

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:

JSON

{
  "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.