Gareth Wilson Gareth Wilson

Guide to ReferralHero Webhooks: Features and Best Practices

Published


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

FeatureDetails
ConfigurationPer campaign: Edit Campaign > Integrations > Webhooks
Signaturebase64 HMAC-SHA256
Signature headerx-referralhero-signature
Signed contentThe raw request body
KeyThe Webhook Secret Key, once Payload Verification is on
BodyJSON, flat subscriber object
Event routingBody field response
Expected reply200 with a blank body
Retries3 times over 5 minutes
Auto-disableAfter 10 consecutive bad responses

Events and payloads

Event (response)Triggered WhenCommon Use Cases
new_registrationA new subscriber registersCreate a CRM contact, send a welcome email
subscriber_promotedA subscriber is promotedGrant early access, move a waitlist position
subscriber_updatedA subscriber is updatedSync changed fields
subscriber_deletedA subscriber is deletedRemove the contact downstream
reward_unlockedA subscriber unlocks a rewardNotify the user, queue fulfilment
reward_sentA reward is sentMark fulfilment complete

ReferralHero's documented example for subscriber_updated sends "response": "subscriber_fields_updated", 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.

  1. Open Edit Campaign > Integrations > Webhooks and add or edit the webhook.
  2. Turn on Payload Verification. A secret key is generated.
  3. 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.
  4. 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

  1. Enter your endpoint URL, for example https://your-app.example.com/webhooks/referralhero.
  2. Toggle on the events you want.
  3. 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_fields_updated 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.