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 an HTTP 200 status code. This indicates that PaySway can safely mark the event as delivered.

3. Retries on Failure

   • If your endpoint returns any status code other than 200, 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 response is received, PaySway treats the event as delivered and will not attempt to send it again.

​

Request structure

PaySway packages each event in a single JSON payload, which includes metadata about when the event occurred and the type of activity, along with an object specific to that event type. The JSON payload has the following fields:

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

​

Event types

Because the object field can vary based on the event type, you should consult the full reference for each event’s specific schema. You can find a detailed breakdown of object structures for all event types here.