Real-time notifications

Overview

Webhooks allow you to receive real-time notifications about events that occur in your Reservepay account. Instead of polling our API to check for updates, your server can listen for incoming requests from Reservepay.

Setting up webhooks

To start receiving webhook notifications, you need to connect a webhook endpoint to your account. You can manage your webhooks either through our API or directly from your merchant dashboard under the Developer Settings section.

Currently supported events

If you have other needs or require additional event types, please contact our support team and we'll be happy to add them for you.

Handling webhook requests

When an event occurs, Reservepay will send a POST request to your destination URL with a JSON payload containing the event details.

Verifying signatures

To ensure that a request genuinely came from Reservepay, you must verify the signature on the raw request body before processing the event. Each webhook endpoint is configured with a signature type when it is connected. Your endpoint's verification key is available in your merchant dashboard and via the webhooks API.

HMAC (SHA256)

Compute an HMAC-SHA256 digest of the raw request body using your verification key (Base64-decoded) and compare it to the hex value after hmac_sha256= in the Reservepay-Signature header.

Ed25519

Verify the hex-decoded signature after ed25519= in the Reservepay-Signature header against the raw request body using your verification key (Base64-decoded Ed25519 public key). Use a libsodium-compatible library for verification.

SHA256 (legacy)

Compute the SHA256 hex digest of the raw request body concatenated with your verification key string and compare it to the value after sha256= in the X-Webhook-Signature header. Prefer HMAC_SHA256 or ED25519 for new integrations.

Responding to webhooks

Your server should respond with a 200 OK status code to acknowledge receipt of the webhook. If your server returns an error or fails to respond, Reservepay will retry the notification with exponential backoff.

Summary of best practices

• Idempotency: Ensure that your webhook handler can handle duplicate notifications gracefully.
• Security: Always verify the webhook signature before processing the request.
• Speed: Process webhooks asynchronously to avoid delaying the response to Reservepay.