## 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

| Event | Description |
| :--- | :--- |
| `PAYMENT_AUTHORIZED` | Triggered when a payment status transitions to `AUTHORIZED`. |
| `PAYMENT_COMPLETED` | Triggered when a payment status transitions to `SUCCESSFUL` or `FAILED`. |
| `PAYMENT_VOIDED` | Triggered when a payment status transitions to `VOIDED`. |
| `PAYMENT_REVERSED` | Triggered when a payment status transitions to `REVERSED`. |
| `PAYOUT_COMPLETED` | Triggered when a payout status transitions to `SUCCESSFUL` or `FAILED`. |

If you have other needs or require additional event types, please [contact our support team](mailto:support@reservepay.com) 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.

| Signature type | Headers | Recommended |
| :--- | :--- | :--- |
| `HMAC_SHA256` | `Reservepay-Signature` | Yes (default) |
| `ED25519` | `Reservepay-Signature` | Yes |
| `SHA256` | `X-Webhook-Signature` | Legacy only |

#### 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.