Webhooks Introduction

Webhooks allow you to stay informed about specific events in xPay by receiving real-time notifications. Here’s everything you need to know about setting up and handling webhooks securely and efficiently.

​

Webhook URL

You will register an endpoint URL to receive events from xPay through the Settings Page, where a signing_key will also be provided for securing the communication between xPay and your system. Make sure your webhook URL is set up to reliably accept these events and handle them as needed.

​

Timeouts

xPay’s system will adhere to a 2-second connection timeout and read timeout for each webhook delivery attempt. If the request exceeds this limit or fails for any reason, xPay will retry sending the event using exponential backoff to avoid overwhelming your system.

​

Idempotency

To ensure robustness in your webhook processing, it’s crucial to handle events idempotently. This means that even if the same event is sent multiple times (due to retries), your system will handle it without causing errors or duplicating operations.

​

Security

Each event payload will be signed using HmacSHA512 with the provided signing_key. To verify the authenticity of the event, compute the HMAC of the payload and compare it with the xpay-signature header value to confirm that the event came from xPay.

​

Sample Payload Header

{
  "xpay-signature" : "s3z2v3ZGwMvDwiQ+9PpAT3WuSYU+PeSZJqvdzZXPmifAh3sT+s502PgJJx9NV4KQaScEaquTEuHJ30v17hK5GA==",
  ...
}