Skip to main content

Webhook Signatures

Verify that webhook requests are actually from OrcaRail by validating webhook signatures.

Why Verify Signatures?​

Webhook signatures ensure that:

  • The request is actually from OrcaRail
  • The payload hasn't been tampered with
  • You're not processing malicious requests

How It Works​

OrcaRail signs each webhook request using HMAC SHA-256 with your webhook secret. Your server should verify this signature before processing the event.

Signature Header​

OrcaRail includes the signature in the x-webhook-signature header:

x-webhook-signature: abc123def456...

Webhook Secret​

The webhook signing secret is your API key secret (sk_live_...) — the same value returned when you created the API key. Configure it via PAYMENTS_WEBHOOK_SECRET (or your app's env var). Keep it secure and never expose it in client-side code.

Verification Process​

1. Get the Signature​

Extract the signature from the x-webhook-signature header:

const signature = req.headers['x-webhook-signature']

2. Compute Expected Signature​

Compute the expected signature using HMAC SHA-256:

const crypto = require('crypto')
const webhookSecret = process.env.PAYMENTS_WEBHOOK_SECRET

// Get the raw request body
const payload = JSON.stringify(req.body)

// Compute HMAC SHA-256
const expectedSignature = crypto
  .createHmac('sha256', webhookSecret)
  .update(payload)
  .digest('hex')

3. Compare Signatures​

Compare the received signature with the expected signature using a timing-safe comparison:

const crypto = require('crypto')

function verifySignature(receivedSignature, expectedSignature) {
  if (!receivedSignature || !expectedSignature) {
    return false
  }

  const receivedBuffer = Buffer.from(receivedSignature)
  const expectedBuffer = Buffer.from(expectedSignature)

  // Use timing-safe comparison to prevent timing attacks
  if (receivedBuffer.length !== expectedBuffer.length) {
    return false
  }

  return crypto.timingSafeEqual(receivedBuffer, expectedBuffer)
}

Complete Example​

Node.js (Express)​

const express = require('express')
const crypto = require('crypto')

const app = express()

// Middleware to capture raw body for signature verification
app.use('/webhooks/orcarail', express.raw({ type: 'application/json' }))

app.post('/webhooks/orcarail', (req, res) => {
  const webhookSecret = process.env.PAYMENTS_WEBHOOK_SECRET

  if (!webhookSecret) {
    console.warn(
      'PAYMENTS_WEBHOOK_SECRET not set, skipping signature verification'
    )
    // In production, you should always verify signatures
    // return res.status(500).json({ error: 'Webhook secret not configured' });
  }

  // Get signature from header
  const receivedSignature = req.headers['x-webhook-signature']

  if (!receivedSignature && webhookSecret) {
    return res.status(400).json({ error: 'Missing webhook signature' })
  }

  // Compute expected signature
  const payload = req.body.toString()
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(payload)
    .digest('hex')

  // Verify signature
  if (webhookSecret && !verifySignature(receivedSignature, expectedSignature)) {
    return res.status(400).json({ error: 'Invalid webhook signature' })
  }

  // Parse JSON payload
  const event = JSON.parse(payload)

  // Process event
  handleWebhookEvent(event)

  res.status(200).json({ received: true })
})

function verifySignature(receivedSignature, expectedSignature) {
  if (!receivedSignature || !expectedSignature) {
    return false
  }

  const receivedBuffer = Buffer.from(receivedSignature)
  const expectedBuffer = Buffer.from(expectedSignature)

  if (receivedBuffer.length !== expectedBuffer.length) {
    return false
  }

  return crypto.timingSafeEqual(receivedBuffer, expectedBuffer)
}

Python (Flask)​

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/orcarail', methods=['POST'])
def webhook():
    webhook_secret = os.environ.get('PAYMENTS_WEBHOOK_SECRET')

    if not webhook_secret:
        return jsonify({'error': 'Webhook secret not configured'}), 500

    # Get signature from header
    received_signature = request.headers.get('x-webhook-signature')

    if not received_signature:
        return jsonify({'error': 'Missing webhook signature'}), 400

    # Get raw request body
    payload = request.get_data()

    # Compute expected signature
    expected_signature = hmac.new(
        webhook_secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    # Verify signature using timing-safe comparison
    if not hmac.compare_digest(received_signature, expected_signature):
        return jsonify({'error': 'Invalid webhook signature'}), 400

    # Parse JSON payload
    event = request.get_json()

    # Process event
    handle_webhook_event(event)

    return jsonify({'received': True}), 200

Ruby (Rails)​

class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def orcarail
    webhook_secret = ENV['PAYMENTS_WEBHOOK_SECRET']

    unless webhook_secret
      return render json: { error: 'Webhook secret not configured' }, status: 500
    end

    received_signature = request.headers['x-webhook-signature']

    unless received_signature
      return render json: { error: 'Missing webhook signature' }, status: 400
    end

    payload = request.body.read

    expected_signature = OpenSSL::HMAC.hexdigest(
      OpenSSL::Digest.new('sha256'),
      webhook_secret,
      payload
    )

    unless ActiveSupport::SecurityUtils.secure_compare(
      received_signature,
      expected_signature
    )
      return render json: { error: 'Invalid webhook signature' }, status: 400
    end

    event = JSON.parse(payload)

    handle_webhook_event(event)

    render json: { received: true }, status: 200
  end
end

Security Best Practices​

1. Always Verify Signatures in Production​

Never skip signature verification in production, even if it's optional:

if (process.env.NODE_ENV === 'production' && !webhookSecret) {
  throw new Error('PAYMENTS_WEBHOOK_SECRET must be set in production')
}

2. Use Timing-Safe Comparison​

Always use timing-safe comparison functions to prevent timing attacks:

  • Node.js: crypto.timingSafeEqual()
  • Python: hmac.compare_digest()
  • Ruby: ActiveSupport::SecurityUtils.secure_compare()

3. Keep Your Secret Secure​

  • Store the webhook secret in environment variables
  • Never commit it to version control
  • Rotate it periodically
  • Use different secrets for different environments

4. Handle Missing Signatures Gracefully​

If the signature is missing, reject the request:

if (!receivedSignature) {
  return res.status(400).json({ error: 'Missing webhook signature' })
}

Testing Without Signatures​

For local development, you can temporarily disable signature verification:

const webhookSecret = process.env.PAYMENTS_WEBHOOK_SECRET

// Skip verification in development if secret not set
if (!webhookSecret && process.env.NODE_ENV === 'development') {
  console.warn('Skipping webhook signature verification in development')
  // Process event without verification
} else {
  // Verify signature
  if (!verifySignature(receivedSignature, expectedSignature)) {
    return res.status(400).json({ error: 'Invalid webhook signature' })
  }
}

:::warning Important Never disable signature verification in production, even for testing. :::

Next Steps​