Implement handler

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"
  }
}