# Guide to ReferralHero Webhooks: Features and Best Practices

[ReferralHero](https://referralhero.com) 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_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](/docs/cli):

```bash
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](https://support.referralhero.com/campaign-builder/integrations/webhooks).

```javascript
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`.

```javascript
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](/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](/webhooks/guides/why-implement-asynchronous-processing-webhooks) explains.

### Make rewards idempotent

A reward delivered twice costs money. Record each reward against the subscriber before delivering it, following the [idempotency guide](/webhooks/guides/implement-webhook-idempotency).

## 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](https://hookdeck.com) shields the webhook from your outages and keeps a verified record of every campaign event.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle ReferralHero webhooks reliably in minutes.