Webhooks

Clubhouse can send HTTP POST requests to your server when specific loyalty events occur. This lets you react to loyalty events in your own systems in real time.

Available events

Setting up a webhook

1. In Clubhouse, go to Settings → Integrations → Webhooks.
2. Click "Add webhook".
3. Enter the URL of your endpoint.
4. Select which events you want to receive.
5. Save. Clubhouse will immediately send a test event to verify your endpoint responds with a 200 status.

Payload format

All webhook payloads are JSON and include an event type, timestamp, and the affected member data.

{
  "event": "member.tier_changed",
  "timestamp": "2024-11-15T09:31:00Z",
  "data": {
    "email": "customer@example.com",
    "name": "Emma Jensen",
    "previous_tier": "Silver",
    "new_tier": "Gold",
    "lifetime_points": 2000
  }
}

Signature verification

Every webhook request includes an X-Clubhouse-Signature header. This is an HMAC-SHA256 signature of the raw request body, signed with your webhook secret.

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry behavior

If your endpoint does not respond with a 2xx status within 10 seconds, Clubhouse will retry the request up to 3 times with exponential backoff (10s, 30s, 90s). After 3 failures, the event is marked as failed and you'll be notified by email.