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-Signatureheader? - Where do I find the ReferralHero Webhook Secret Key, and what is Payload Verification?
- How do I handle
new_registration,subscriber_promoted,reward_unlockedorreward_sentevents? - Why does my ReferralHero signature check fail, or why was my webhook disabled?
Verification (core)
| Item | Value |
|---|---|
| Header | X-ReferralHero-Signature: bare base64, no prefix |
| Algorithm | HMAC-SHA256, standard base64 (padded, 44 characters) |
| Signed content | The raw request body bytes only (no timestamp, id or other header) |
| Key | The 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_, 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 useREFERRALHERO_.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:
response | Fired when |
|---|---|
new_registration | A new subscriber registers |
subscriber_promoted | A subscriber is promoted |
subscriber_updated | A subscriber is updated (see note) |
subscriber_deleted | A subscriber is deleted |
reward_unlocked | A subscriber unlocks a reward |
reward_sent | A reward is sent |
The docs' subscriber_updated example carries "response": "subscriber_. 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
- references/overview.md - Events, delivery and retry behaviour
- references/setup.md - Adding a webhook, enabling Payload Verification, finding the secret
- references/verification.md - Signature details, gotchas, debugging