Overview

Getting Started

This guide will walk you through setting up and securely handling webhooks. Our implementation follows the Standard Webhooks specification. Your webhook setup is simple: just define the URL where you want to receive event data. Here’s the Webhook Payloads page. Follow these steps to set up your webhook:

Idempotency (The “No Duplicates” Rule): Each webhook event includes a unique x-hyperrails-webhook-id header. Use this identifier to ensure duplicate webhook deliveries are safely ignored.

Securing Webhooks: Trust, but Verify

Every webhook request includes:

x-hyperrails-webhook-id – Unique identifier for the event.
x-hyperrails-webhook-timestamp – Unix timestamp (seconds) when the webhook was signed.
x-hyperrails-signature – HMAC-SHA512 signature, hex-encoded.

Signed content

The signature is computed over the following string (fields joined by a single period, no extra whitespace): .. using your Webhook Secret Key (found at Dashboard → Credentials → API Keys → Webhooks) as the HMAC key. Test and live mode each have their own webhook secret and webhook URL — configure both independently if you run staging and production listeners.

Verification example (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, headers, webhookSecret) {
  const signedContent = `${headers['x-hyperrails-webhook-id']}.${headers['x-hyperrails-webhook-timestamp']}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha512', webhookSecret)
    .update(signedContent)
    .digest('hex');

  const timestampAgeSeconds = Math.abs(Date.now() / 1000 - Number(headers['x-hyperrails-webhook-timestamp']));
  if (timestampAgeSeconds > 300) return false; // reject if older than 5 minutes

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(headers['x-hyperrails-signature'])
  );
}

Use a constant-time comparison (crypto.timingSafeEqual or equivalent) — never === — to avoid timing attacks.

When receiving a webhook:

Verify the x-hyperrails-webhook-timestamp is within an acceptable time window (for example, 5 minutes).
Recompute the signature using your webhook secret, the timestamp, and the raw request payload.
Compare the computed signature with x-hyperrails-signature.
Process the webhook only if both the timestamp and signature are valid.

Ordering is Not Guaranteed: Webhook events may be delivered out of order due to network retries. Always use the x-hyperrails-webhook-id or other data within the payload to ensure correct event processing, regardless of arrival sequence.

You will always receive the latest payload data at the time of delivery, regardless of when the webhook event was initially emitted.

Core Concepts

Supported Currencies

Testing

Features

Webhooks

Expert Desk

Getting Started

Securing Webhooks: Trust, but Verify

Signed content

Verification example (Node.js)

​Getting Started

​Securing Webhooks: Trust, but Verify

​Signed content

​Verification example (Node.js)

Getting Started

Securing Webhooks: Trust, but Verify

Signed content

Verification example (Node.js)