> ## Documentation Index
> Fetch the complete documentation index at: https://doc.raliopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

This document describes the webhooks that RALIO sends to merchants to notify important events.

<Note>
  Webhooks are HTTP notifications sent in real-time when relevant events occur in the system.
</Note>

## What are webhooks?

Webhooks are HTTP POST requests that RALIO sends to your configured endpoint URL when specific events occur. They contain JSON payloads with event data, allowing your system to react immediately to changes.

<CardGroup cols={2}>
  <Card title="Real-time notifications" icon="bolt">
    Receive instant updates when events happen in your RALIO account
  </Card>

  <Card title="Secure delivery" icon="shield">
    All webhook deliveries are signed and can be verified for authenticity
  </Card>

  <Card title="Reliable delivery" icon="rotate-right">
    Failed deliveries are automatically retried with exponential backoff
  </Card>

  <Card title="Event filtering" icon="filter">
    Subscribe only to the events that matter to your application
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Subscribe to webhooks">
    Configure your webhook endpoint and select the events you want to receive through the **Ralio Management Portal**.

    **Sandbox Environment:**

    * Portal: **[https://portal.sandbox.raliopay.com/account/webhooks](https://portal.sandbox.raliopay.com/account/webhooks)**
    * API Base URL: **[https://sandbox-revo-api.raliopay.com](https://sandbox-revo-api.raliopay.com)**

    **Production Environment:**

    * Portal: **[https://portal.raliopay.com/account/webhooks](https://portal.raliopay.com/account/webhooks)**
    * API Base URL: **[https://api.revopaymsb.com](https://api.revopaymsb.com)**
  </Step>

  <Step title="Handle webhook events">
    Process incoming webhook requests in your application endpoint.
  </Step>

  <Step title="Verify webhook signatures">
    Ensure the authenticity of webhook deliveries by verifying signatures.
  </Step>
</Steps>

## Required Configuration

To receive webhooks, merchants must configure the following elements:

### 1. Endpoint HTTPS

<Warning>
  Your webhook endpoint must meet these requirements for reliable delivery.
</Warning>

* Must be a valid HTTPS endpoint that accepts POST requests
* Must be accessible from the internet
* Must respond within a reasonable time (timeout configured to 60 seconds)

### 2. Authentication

<Info>
  RALIO uses HMAC-SHA256 signatures to ensure webhook authenticity and prevent tampering.
</Info>

**Signature Generation Process:**

* RALIO generates an HMAC-SHA256 signature using the complete webhook payload and your webhook secret
* The signature is calculated as: `HMAC-SHA256(webhook_payload, webhook_secret)`
* The resulting signature is sent in the `X-Signature` header with each webhook delivery

**Verification Steps:**

1. Extract the `X-Signature` header from the incoming webhook request
2. Generate your own signature using the request body and your stored webhook secret
3. Compare your generated signature with the received signature
4. Only process the webhook if signatures match exactly

<Warning>
  Always verify webhook signatures before processing the payload to ensure the request originates from RALIO and hasn't been tampered with.
</Warning>

### 3. Response Handling

Your endpoint's response behavior determines delivery success and retry logic:

**Success Criteria:**

* The endpoint must respond with an HTTP 2xx status code to indicate success
* Response body content is logged for auditing purposes but doesn't affect success determination

**Error Handling:**

* Any non-2xx status code will be considered a delivery failure
* Failed deliveries automatically trigger retry attempts with exponential backoff
* Both the status code and response body are stored for troubleshooting

**Delivery Auditing:**

* RALIO logs all webhook delivery attempts including status codes and response bodies
* You can retrieve delivery history and details through the **Ralio Management Portal**
* Failed deliveries can be manually retried from the portal's webhook management interface

### 4. HTTP Headers

Webhooks include the following headers:

<CodeGroup>
  ```http Request Headers theme={null}
  Accept: application/json
  Content-Type: application/json
  X-Signature: <hmac_sha256_signature>
  X-Trace-ID: <trace_id>
  ```
</CodeGroup>

<CardGroup cols={2}>
  <Card title="Accept" icon="check">
    **application/json** - Indicates the expected response format
  </Card>

  <Card title="Content-Type" icon="file-code">
    **application/json** - Webhook payload format
  </Card>

  <Card title="X-Signature" icon="shield">
    **HMAC-SHA256** - Message authentication signature
  </Card>

  <Card title="X-Trace-ID" icon="magnifying-glass">
    **Optional** - Unique identifier for request tracing and debugging
  </Card>
</CardGroup>