Skip to main content
This document describes the webhooks that RALIO sends to merchants to notify important events.
Webhooks are HTTP notifications sent in real-time when relevant events occur in the system.

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

Real-time notifications

Receive instant updates when events happen in your RALIO account

Secure delivery

All webhook deliveries are signed and can be verified for authenticity

Reliable delivery

Failed deliveries are automatically retried with exponential backoff

Event filtering

Subscribe only to the events that matter to your application

​
Getting Started

1

Subscribe to webhooks

Configure your webhook endpoint and select the events you want to receive through the Ralio Management Portal.Sandbox Environment:Production Environment:
2

Handle webhook events

Process incoming webhook requests in your application endpoint.
3

Verify webhook signatures

Ensure the authenticity of webhook deliveries by verifying signatures.

​
Required Configuration

To receive webhooks, merchants must configure the following elements:

​
1. Endpoint HTTPS

Your webhook endpoint must meet these requirements for reliable delivery.
  • 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

RALIO uses HMAC-SHA256 signatures to ensure webhook authenticity and prevent tampering.
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
Always verify webhook signatures before processing the payload to ensure the request originates from RALIO and hasn’t been tampered with.

​
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: 
Accept: application/json
Content-Type: application/json
X-Signature: <hmac_sha256_signature>
X-Trace-ID: <trace_id>

Accept

application/json - Indicates the expected response format

Content-Type

application/json - Webhook payload format

X-Signature

HMAC-SHA256 - Message authentication signature

X-Trace-ID

Optional - Unique identifier for request tracing and debugging