Webhooks

Overview

The PlatformNext webhook system enables integrators to receive real-time updates for events. This allows for seamless integration and faster response to critical changes, such as payment status updates.

Setup

Webhook Setup

To start receiving webhook events, follow the steps below to create a webhook handler and add it to your merchant using the PlatformNext API.

Create a Webhook Endpoint

First, implement a webhook handler on your server to accept incoming HTTP POST requests from PlatformNext. This endpoint should:

Accept application/json POST requests
Read the request body as a serialized JSON string
Deserialize the payload string into the appropriate format.
Respond quickly with a 200 OK status to acknowledge receipt

Add to Merchant

To activate webhooks for a specific merchant, use the PlatformNext API to add the webhook endpoint to your Merchant.

Payload

Each webhook event sends an HTTP POST request with a payload that consists of a serialized JSON string. This string represents the DTO object associated with the event type.

Content Type:
Content-Type: application/json

Payload Format:

The body of the request is a JSON-encoded string, meaning it must be deserialized as a string first, and then parsed into a usable object.

Example:

JSON

"{\"paymentId\":\"a2f70b3f-1925-41bb-92a7-8e675b3c7df3\",\"merchantId\":\"cf1eab5e-5d98-4a61-a8f5-349f6f7d263a\",\"timeStamp\":\"2025-05-23T15:30:00Z\",\"externalPaymentId\":\"EXT-001234\",\"status\":\"Completed\",\"pendingReason\":null,\"rejectReason\":null,\"returnCode\":null,\"returnReason\":null,\"event\":1}"

To process this:

Deserialize the outer string from the HTTP request body.
Parse the resulting JSON to extract structured fields.

Warning: The structure of the payload will vary depending on the event type. Each event maps to a different DTO.

Error Handling

PlatformNext is designed to ensure reliable delivery of webhook events. If a webhook attempt fails, the system will automatically retry the delivery using an exponential backoff strategy for up to 30 hours.

Retry Behavior

Initial attempt: Triggered immediately when the event occurs.
Subsequent retries: Start shortly after the first failure and grow progressively longer (exponential backoff).
Retry window: Retries will continue for up to 30 hours after the initial event was created.
Max retries: The total number of retry attempts is 13.

What Counts as a Failure?

A webhook delivery is considered failed if:

The HTTP response status is not in the 2xx success range.
The request times out (no response within 10 seconds).
The connection is refused or the endpoint is unreachable.

Payment Status Update Event

The Payment Status Update Event webhook generates an event when a payment's status changes, provided the merchant has a webhook endpoint configured and enabled on their account.

The following is an example of a webhook payload for a Payment Status Update.

JSON

{
  "paymentId": "a2f70b3f-1925-41bb-92a7-8e675b3c7df3",
  "merchantId": "cf1eab5e-5d98-4a61-a8f5-349f6f7d263a",
  "timeStamp": "2025-05-23T15:30:00Z",
  "externalPaymentId": "EXT-001234",
  "status": 1,
  "pendingReason": null,
  "rejectReason": null,
  "returnCode": null,
  "returnReason": null,
  "event": 1
}

Tip: You can reference the event field to determine the type of DTO expected. For instance, event = 1 corresponds to a Payment Status Update.