Agent skill

ReferralHero Webhooks Skill

Receive and verify ReferralHero webhooks (referral and waitlist campaigns). Use when setting up a ReferralHero webhook endpoint, enabling Payload Verification, debugging X-ReferralHero-Signature (base64 HMAC-SHA256 of the raw body) failures, or handling new_registration, subscriber_promoted, subscriber_updated, subscriber_deleted, reward_unlocked and reward_sent events.

Install this skill

npx skills add hookdeck/webhook-skills --skill referralhero-webhooks


ReferralHero runs referral and waitlist campaigns. Webhooks are added per campaign (Edit Campaign > Integrations > Webhooks) with the events you want toggled on, and each delivery is signed with the X-ReferralHero-Signature header.

Signing is opt-in: turn on Payload Verification for the ReferralHero webhook and paste the Webhook Secret Key. Without it, deliveries are unsigned and fail verification.

When to Use This Skill

  • How do I receive ReferralHero webhooks?
  • How do I verify the X-ReferralHero-Signature header?
  • Where do I find the ReferralHero Webhook Secret Key, and what is Payload Verification?
  • How do I handle new_registration, subscriber_promoted, reward_unlocked or reward_sent events?
  • Why does my ReferralHero signature check fail, or why was my webhook disabled?

Verification (core)

ItemValue
HeaderX-ReferralHero-Signature: bare base64, no prefix
AlgorithmHMAC-SHA256, standard base64 (padded, 44 characters)
Signed contentThe raw request body bytes only (no timestamp, id or other header)
KeyThe Webhook Secret Key as UTF-8 bytes, used as-is (not decoded)
const crypto = require('crypto');

// rawBody: Buffer of the exact request bytes (express.raw({ type: '*/*' })), NOT re-serialised JSON
function verifyReferralHeroSignature(rawBody, signature, secret = process.env.REFERRALHERO_WEBHOOK_SECRET) {
  if (!signature || !secret || !/^[A-Za-z0-9+/]{43}=$/.test(signature)) return false; // validate format first
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');
  const a = Buffer.from(signature, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b); // exact, case-sensitive text compare
}

Python: check re.fullmatch(r"[A-Za-z0-9+/]{43}=", sig), base64.b64decode(sig, validate=True), then hmac.compare_digest on bytes against hmac.new(secret.encode(), raw_body, hashlib.sha256).digest(), and also against the re-encoded text. Respond 401 for a missing, empty, malformed or mismatched signature.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Key points:

  • Use the raw body. Parsing and re-serialising JSON changes the bytes and breaks the signature.
  • Compare the base64 text exactly. A value whose last character carries stray bits decodes to the same bytes but must still be rejected, so don't rely on decoding alone, and never call Buffer.from(sig, 'base64') on an unvalidated value.
  • No timestamp is signed, so there is no replay window to enforce. Don't invent one.
  • ReferralHero's code samples read the key from REFERRALHERO_API_KEY, but the key is the Webhook Secret Key, not your API key. These examples use REFERRALHERO_WEBHOOK_SECRET.

Responding

Reply 200 with a blank body; anything else is an error. Failed deliveries are retried 3 times over 5 minutes, and 10 consecutive bad responses disable the webhook. The Test button sends fake data.

Event Handling

Dispatch on the body's top-level response field:

responseFired when
new_registrationA new subscriber registers
subscriber_promotedA subscriber is promoted
subscriber_updatedA subscriber is updated (see note)
subscriber_deletedA subscriber is deleted
reward_unlockedA subscriber unlocks a reward
reward_sentA reward is sent

The docs' subscriber_updated example carries "response": "subscriber_fields_updated". The docs don't reconcile the two, so handle both values until you capture a real delivery. The method is POST.

Environment Variables

REFERRALHERO_WEBHOOK_SECRET=your_webhook_secret_key_here   # handlers fail closed (500) without it

The secret appears under the profile menu (Webhook Secret, with regenerate) and on each campaign's Integration > Webhook tab, once Payload Verification is enabled.

Local Development

# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 referralhero --path /webhooks/referralhero

Add the printed URL as the webhook URL in ReferralHero, then use the Test button.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →