📘

Learn how to receive webhook notifications from Payrails to stay informed about the outcomes of asynchronous actions such as authorize, capture, cancel, refund, and more.

Introduction

A notification is a webhook sent by Payrails to inform you of the outcome of an asynchronous action such as authorization, capture, cancellation, refund, etc. Notifications are sent to specified endpoints on your server in JSON format using the HTTP POST method.

To start receiving notifications, follow these steps:

1. Expose an Endpoint on Your Server

Create an exposed endpoint on your server that accepts HTTP requests in JSON format.

2. Configure Endpoint URL(s) in Payrails Portal

Navigate to the Payrails Portal to configure the endpoint URL(s) where you want to receive notifications. To do this, go to Configurations > Settings in the Portal menu. Add the endpoint URL(s) under the Notifications section, and click on "Save changes".

You will now start receiving notifications for new executions at your saved URL(s), and each URL will receive for each execution the notifications detailed in our list of notification types. Notifications for existing executions will continue to be delivered to the URLs in place when those executions were created.

You can review, add, or delete the URLs from this page at any time.

3. Accept Notifications

Notifications will be sent using the HTTP POST method in the format shown below. Each notification request contains an X-Signature header, which is a signature of the request body. The signature is calculated using the HMAC-SHA256 algorithm and a secret key.

Calculate and Verify the HMAC Signature
To verify the X-Signature header's value, calculate the HMAC signature as described above, and compare it to the header value. If they match, the notification is valid.

Example:

Secret Key: 44782DEF547AAA06C910C43932B1EB0C71FC68D9D0C057550C48EC2ACF6BA056

Request Header: X-Signature: /9RS0Gfxl2C6j1akmI5/l0y+FTygmNmEPU/2nNYMYTQ=

Order of Notifications
Payrails does not guarantee the order of notifications. For example, an authorization notification might fail, followed by a successful capture notification, and then a successful retry of the authorization notification. Your endpoint should handle notifications received out of order, possibly by fetching the latest state of the object from the API.

Retry Mechanism
If the notification is valid, acknowledge it with a HTTP 200 response
If the initial notification delivery fails, Payrails will attempt to resend it up to 50 times using an exponential back-off strategy, over a period of several days.

4. Track Notifications

You can review the status and destination of notifications for each execution in the Payrails Portal or by using the Search & list events API.

Go to the Executions page, search by execution ID, and review the details page for the selected execution. The information about notifications can be found in the Execution Timeline section.

Click on any completed event in the timeline to view the corresponding notification object in the payload.

5. Understand Notification Types

Payrails sends notifications for various events related to execution and payment state changes. Consult the exhaustive list of notification types to understand the different types of notifications you might receive.

By following this guide, you'll be well-equipped to receive and handle webhook notifications from Payrails, ensuring that you're always up-to-date with the status of your payment transactions.