Webhooks 🔌

Webhooks are HTTP callbacks that deliver notification messages for events. Peach Payments uses webhooks to notify merchant systems when certain transaction events occur. This way, your servers are always up to date with transaction information.

After a webhook has been configured and verified, Peach Payments delivers POST notifications to the specified URL for the following events:

Webhook eventDescription
initiatedTriggered when the payment link is created.
processingTriggered when the payment is attempted.
completedTriggered when the payment is successfully completed.
cancelledTriggered when the payment is cancelled.
expiredTriggered when the payment link expires.


  1. Merchants can configure webhooks in one of two ways:
  2. The webhook is triggered for pre-defined events as described above.
  3. The merchant then triggers a query to pull transaction details and statuses.

Webhook retry mechanism

Peach Payments expects a 200 HTTP for successful webhook delivery and a non-200 HTTP status code for failures.

In case of an unsuccessful response, Peach Payments retries the webhook until a successful acknowledgement (200 HTTP) occurs.

Exponential backoff retry

Below is the exponential backoff logic.

The intervals between retries will be:

  • 1 minute
  • 2 minutes
  • 4 minutes
  • 8 minutes
  • 15 minutes
  • 30 minutes
  • 1 hour
  • Every day until 30 days have passed since the first attempt

Webhook event responses

The following are some of the triggered webhook event responses.

  "status": "initiated",
  "url": "https://qa-v2.ppay.io/2c81cb0406171e9a",
  "paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
  "status": "expired",
  "paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
  "status": "processing",
  "paymentId": "ee0d5e12-2d46-43e0-bb2d-228e5f9ce86c"
  "status": "completed",
  "paymentId": "ee0d5e12-2d46-43e0-bb2d-228e5f9ce86c"