recurly-webhooks

Recurly Webhooks

When to Use This Skill

• How do I receive Recurly webhooks?
• How do I verify the Recurly recurly-signature header?
• How do I secure a Recurly webhook endpoint with HTTP Basic Auth?
• How do I handle new_subscription_notification or successful_payment_notification?
• Why is my Recurly webhook signature verification failing?

How Recurly Secures Webhooks

Recurly webhooks are secured with up to three layers. Use all that apply:

1. Signature (JSON payloads only). Recurly signs JSON notifications and sends the signature in a recurly-signature header. This is the primary integrity check — always verify it. (Legacy XML payloads are not signed.)
2. HTTP Basic Auth. Configure a username/password on the endpoint in Recurly; Recurly sends them in the Authorization header on every request.
3. IP allowlist. Accept requests only from Recurly's published IP ranges.

Prefer the JSON payload format so you get signature verification. The official Recurly SDK (recurly) is an API client and does not ship a webhook verification helper, so verify the signature manually with HMAC-SHA256.

Verification (core)

The recurly-signature header is a Unix timestamp (ms) followed by one or more hex HMAC-SHA256 signatures, comma-separated:

recurly-signature: 1659641851000,a8c8524a0cdd99e3...,cafe677a2e6fa177...

Signed message is `${timestamp}.${rawBody}` (the raw, unparsed body). Multiple signatures appear during a 24h key rotation; the notification is valid if any one matches. Use a constant-time compare.

const crypto = require('crypto');

function verifyRecurlySignature(rawBody, header, secret) {
  if (!header || !secret) return false;
  const [timestamp, ...signatures] = header.split(',');
  if (!timestamp || signatures.length === 0) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)                 // Buffer/string of the raw request body
    .digest('hex');

  const expBuf = Buffer.from(expected);
  return signatures.some((sig) => {
    const sigBuf = Buffer.from(sig.trim());
    return sigBuf.length === expBuf.length && crypto.timingSafeEqual(sigBuf, expBuf);
  });
}