# ReferralHero Webhooks

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

| 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) |

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/referralhero-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/referralhero-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/referralhero-webhooks/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:

| `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_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

```bash
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

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/referralhero-webhooks/references/overview.md) - Events, delivery and retry behaviour
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/referralhero-webhooks/references/setup.md) - Adding a webhook, enabling Payload Verification, finding the secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/referralhero-webhooks/references/verification.md) - Signature details, gotchas, debugging