Guide to ReferralHero Webhooks: Features and Best Practices
ReferralHero powers referral programmes and viral waitlists: people sign up, get a referral link, climb the queue as friends join, and unlock rewards at milestones. The product or launch behind the campaign usually lives elsewhere, so ReferralHero's webhooks are what tell your app to create an account, grant early access when someone is promoted, or deliver a reward.
This guide covers ReferralHero's six campaign events and a naming conflict in one of them, turning on Payload Verification, checking the base64 X-ReferralHero-Signature, and the short retry window that can disable a webhook.
What are ReferralHero webhooks?
Webhooks are configured per campaign under Edit Campaign > Integrations > Webhooks. You add an endpoint URL and toggle the events it should receive, and a Test button sends fake data.
Each delivery is a JSON POST describing the subscriber: list UUID, subscriber ID, names and email, with referrer and reward details on the events that need them. The event name is in the body's response field.
Signing is off until you enable Payload Verification on the webhook. Then each request carries X-ReferralHero-Signature, a base64 HMAC-SHA256 of the raw body.
ReferralHero webhook features
| Feature | Details |
|---|---|
| Configuration | Per campaign: Edit Campaign > Integrations > Webhooks |
| Signature | base64 HMAC-SHA256 |
| Signature header | x-referralhero-signature |
| Signed content | The raw request body |
| Key | The Webhook Secret Key, once Payload Verification is on |
| Body | JSON, flat subscriber object |
| Event routing | Body field response |
| Expected reply | 200 with a blank body |
| Retries | 3 times over 5 minutes |
| Auto-disable | After 10 consecutive bad responses |
Events and payloads
Event (response) | Triggered When | Common Use Cases |
|---|---|---|
new_registration | A new subscriber registers | Create a CRM contact, send a welcome email |
subscriber_promoted | A subscriber is promoted | Grant early access, move a waitlist position |
subscriber_updated | A subscriber is updated | Sync changed fields |
subscriber_deleted | A subscriber is deleted | Remove the contact downstream |
reward_unlocked | A subscriber unlocks a reward | Notify the user, queue fulfilment |
reward_sent | A reward is sent | Mark fulfilment complete |
ReferralHero's documented example for subscriber_updated sends "response": "subscriber_, and the docs don't say which value is correct. Accept both until a real delivery confirms which one your campaign sends.
Event Payload Structure
Bodies are flat: response first, then list_uuid, subscriber_id, name, first_name, last_name, email and other subscriber fields. Promotion and reward events add referrer and reward details. There's no delivery or event ID. ReferralHero's examples include // comments and, in older ones, unquoted keys, so they can't be used as JSON fixtures directly.
Setting up ReferralHero webhooks
Prerequisites
- A ReferralHero account with a campaign
- A public HTTPS endpoint
Get Your Webhook Secret Key
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.
- Open Edit Campaign > Integrations > Webhooks and add or edit the webhook.
- Turn on Payload Verification. A secret key is generated.
- Copy the Webhook Secret Key. It's also under the profile menu (Webhook Secret, where you can regenerate it) and on each campaign's webhook tab.
- Store it as
WEBHOOK_SECRET, exactly as shown.
ReferralHero's code samples read the key from a variable called REFERRALHERO_API_KEY, but the value is the Webhook Secret Key, not your API key.
Register Your Endpoint
- Enter your endpoint URL, for example
https://your-app.example.com/webhooks/referralhero. - Toggle on the events you want.
- Save, then press Test to send fake data.
Test a delivery
Start a local receiver and forward requests with the Hookdeck CLI:
npx hookdeck-cli listen 3000 referralhero --path /webhooks/referralhero
Add the CLI's URL as a webhook with Payload Verification on, press Test, and confirm the base64 signature verifies. Then sign up to your own waitlist to see a real new_registration.
Securing ReferralHero webhooks
Compute HMAC-SHA256 of the raw body with the Webhook Secret Key, base64-encode it (standard alphabet, padded), and compare it with X-ReferralHero-Signature in constant time. ReferralHero's Ruby, Python and Node samples all use base64 (strict_encode64, b64encode, digest('base64')). See the webhooks article.
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-referralhero-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
The handler accepts both spellings of the update event, keys repeats on a hash of the body (there's no event ID), and replies with an empty 200.
const express = require('express');
function createReferralHeroApp({ claim, users, rewards }) {
const app = express();
app.post('/webhooks/referralhero', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
let payload;
try {
payload = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
return res.sendStatus(400);
}
if (typeof payload.response !== 'string') return res.sendStatus(400);
try {
const bodyHash = crypto.createHash('sha256').update(req.body).digest('hex');
if (await claim(bodyHash)) {
switch (payload.response) {
case 'new_registration':
await users.createFromWaitlist(payload);
break;
case 'subscriber_promoted':
await users.grantEarlyAccess(payload.email);
break;
case 'subscriber_updated':
case 'subscriber_fields_updated':
await users.syncFields(payload);
break;
case 'subscriber_deleted':
await users.removeFromWaitlist(payload.subscriber_id);
break;
case 'reward_unlocked':
case 'reward_sent':
await rewards.record(payload.response, payload);
break;
default:
console.log('Unhandled ReferralHero event', payload.response);
}
}
} catch {
return res.sendStatus(503);
}
return res.status(200).end();
});
return app;
}
No timestamp is signed, so the signature can't tell a replay from the original. The body hash catches exact repeats; for rewards, also check that you haven't already delivered the reward to that subscriber.
Hookdeck's ReferralHero source type verifies the base64 X-ReferralHero-Signature against the raw body using your Webhook Secret Key. ReferralHero gets a 200 from Hookdeck whatever the result, so outages on your side don't count towards the 10-error limit; a bad signature is recorded as failed verification and not forwarded. Hookdeck applies no timestamp tolerance. ReferralHero asks for a blank response body, so check its webhook status after the first delivery through Hookdeck and set a custom response on the source if ReferralHero flags errors. If you choose to leave Payload Verification off, leave verification off on the source too.
Make ReferralHero webhooks production-ready. Hookdeck Event Gateway keeps ReferralHero's webhook from being disabled during your outages, verifies each signed delivery, and stores every sign-up and reward event for replay.
ReferralHero webhook limitations and pain points
Five minutes of retries, then disabled
The Problem: A short outage loses sign-ups, and a slightly longer one switches the webhook off.
Why It Happens: A failure is retried 3 times over 5 minutes, and 10 consecutive bad responses disable the webhook.
Workarounds:
- Monitor the webhook's status and re-enable it quickly.
- Export or query subscribers after an incident to fill gaps.
How Hookdeck Can Help: Hookdeck accepts every delivery, so ReferralHero never sees your failures, and events wait in Hookdeck until your service recovers.
Signing is off by default
The Problem: An unsigned webhook lets anyone post fake registrations or reward events.
Why It Happens: Payload Verification is an opt-in toggle on each webhook.
Workarounds:
- Turn it on for every webhook and reject unsigned requests.
How Hookdeck Can Help: A ReferralHero source with verification on logs unsigned requests as failed and never forwards them.
A strict response format
The Problem: Deliveries count as errors even though your endpoint returned 200.
Why It Happens: ReferralHero expects a blank body, and treats anything else as an error.
Workarounds:
- Send an empty
200, as in the handler above.
How Hookdeck Can Help: Hookdeck's response to ReferralHero is set on the source, independently of what your service returns.
Conflicting event name and no IDs
The Problem: Update events are missed or processed twice.
Why It Happens: The documented example sends subscriber_ under a subscriber_updated heading, and there's no event ID for deduplication.
Workarounds:
- Handle both names.
- Deduplicate on a body hash or on subscriber ID plus event.
How Hookdeck Can Help: Hookdeck's request log shows the exact response value your campaign sends, and its deduplication can drop identical bodies.
Best practices
Keep the secret straight
Use the Webhook Secret Key from Payload Verification, not the API key. If you regenerate it from the profile menu, update every receiver straight away.
Compare base64 carefully
Validate the header's format before decoding, and check that the decoded value re-encodes to the same text. Buffer.from(sig, 'base64') silently drops invalid characters.
Acknowledge fast
ReferralHero doesn't state a timeout, and its retry window is short. Store the body, reply with an empty 200, and process in the background, as our asynchronous processing guide explains.
Make rewards idempotent
A reward delivered twice costs money. Record each reward against the subscriber before delivering it, following the idempotency guide.
Conclusion
ReferralHero's webhooks are a simple feed of waitlist and referral events, with a base64 HMAC once you enable Payload Verification. The risks are operational: signing that's off by default, a five-minute retry window, auto-disable after 10 errors, a strict blank-body response, and a conflicting name for update events.
Hookdeck Event Gateway shields the webhook from your outages and keeps a verified record of every campaign event.
Get started with Hookdeck for free and handle ReferralHero webhooks reliably in minutes.