When you build a webhook endpoint to receive events from PaySway, your handler must be prepared for both successful and failed deliveries, as well as the structure of the JSON payload that arrives with each event. Below are key considerations and technical details to help you implement a robust endpoint.

​
Delivery and retry logic

PaySway delivers events one at a time, sending each as a separate HTTP request to your webhook endpoint. Here’s how delivery and retries work:
1

Single-event requests

Each HTTP request contains exactly one event in JSON format.
2

Successful deliveries

If your handler processes an event successfully, it should return a 200 OK response status. This indicates that PaySway can safely mark the event as delivered.
3

Retries on failure

If your endpoint returns any status other than 200 OK, the delivery is considered failed. PaySway will retry delivering that event using an exponential backoff strategy. There is no limit on the number of retry attempts, so your handler should be idempotent and prepared for possible repeated messages.
4

Independent deliveries

Failed deliveries for one event do not prevent PaySway from sending subsequent events. Each event is processed independently in its own request.
5

Final confirmation

As soon as a 200 OK response is received, PaySway treats the event as delivered and will not attempt to send it again.

​
Payload structure

PaySway packages each event in a single JSON payload with metadata and event-specific data:
​
id
string (uuid)
required
A unique identifier for the event. Use this for idempotency checks.
​
createdAt
string (date-time)
required
The date and time the event was created, formatted as ISO 8601.
​
eventType
string (enum)
required
The type of event that occurred. See event types for all available values.
​
object
object
required
A structured event object containing event-specific data. The schema varies by event type.

​
Example payload

{
  "id": "45239619-07eb-47c7-9a58-f98650c269ba",
  "createdAt": "2025-01-26T21:28:04.000Z",
  "eventType": "RECIPIENT.CREATED",
  "object": {
    "id": "ed110f81-efab-434a-ba5f-0efcf5f11eeb",
    "externalUserId": "4173663e-7fec-4daa-8c8a-b41644645a52"
  }
}