Features

Webhooks

Webhooks overview

Webhooks allow you to receive real-time HTTP notifications whenever someone joins your waitlist. This enables you to automate workflows, update external systems, and create custom integrations with your favorite tools.

Webhooks are available on the Pro plan and above.

Benefits of Webhooks

Using webhooks with your waitlist provides powerful automation capabilities.

Real-time Integration: Instantly sync new subscribers to your CRM, email platform, or analytics tools
Custom Workflows: Trigger automated processes like Slack notifications, database updates, or custom logic
Reliable Delivery: Secure HTTPS delivery with HMAC verification and automatic retry logic
Complete Data: Receive subscriber information including metadata and referral details

Setting Up Webhooks

Configuring Your Webhook

To set up a webhook for your waitlist, follow these steps.

Navigate to your waitlist dashboard
Go to "Integrations" in the sidebar navigation
Click "Manage" on the "Webhooks" card
Enter your webhook URL and optional secret
Test your webhook to make sure it's working correctly

Webhook URL Requirements

Your webhook endpoint must meet these requirements:

HTTPS only: All webhook URLs must use secure HTTPS connections
Fast response: Your endpoint should respond within 15 seconds
Return 2xx status: Return any 2xx HTTP status code to indicate successful receipt
Handle retries: Be prepared to receive the same webhook multiple times

Webhook Payload

When someone joins your waitlist, we'll send a POST request to your webhook URL with the following payload:

{
  "event": "waitlist.signup_created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "signup_abc123",
    "email": "[email protected]",
    "name": "John Doe",
    "position": 42,
    "points": 50,
    "referral_code": "happy-star-4f3d",
    "referred_by": "friend-code-123",
    "waitlist": {
      "key": "your-waitlist-key",
    },
    "metadata": {
      "referring_domain": "google.com",
      "user_agent": "Mozilla/5.0...",
      "source": "landing-page",
      "origin_url": "https://yoursite.com",
      "city": "New York",
      "region": "NY",
      "country": "US",
      "timezone": "America/New_York",
      "custom_fields": {},
      "signup_date": 1642248600000
    }
  }
}

Payload Fields

Field	Type	Description
`event`	string	Always `"waitlist.signup_created"`
`timestamp`	string	ISO 8601 timestamp when the webhook was sent
`data.id`	string	Unique identifier for the sign-up
`data.email`	string	Subscriber's email address
`data.name`	string\|null	Subscriber's name (if provided)
`data.position`	number	Current position in the waitlist
`data.points`	number	Current points
`data.referral_code`	string	Unique referral code for this subscriber
`data.referred_by`	string\|null	Referral code that referred this subscriber
`data.waitlist`	object	Information about the waitlist
`data.metadata`	object	Additional context and tracking information

Security & Verification

HMAC Signature Verification

For added security, you can configure a webhook secret. When provided, we'll include an HMAC SHA-256 signature in the request headers.

Headers

X-Webhook-Signature: sha256=your-computed-signature
X-Waitlister-Event: waitlist.signup_created
X-Waitlister-Delivery: unique-delivery-id
X-Waitlister-Timestamp: 2025-01-15T10:30:00Z

Verification Examples

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = 'sha256=' + 
    crypto.createHmac('sha256', secret)
          .update(payload, 'utf8')
          .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Usage
const isValid = verifyWebhook(
  JSON.stringify(req.body),
  req.headers['x-webhook-signature'],
  'your-secret'
);

Python

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected_signature = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

# Usage
is_valid = verify_webhook(
    request.get_data(as_text=True),
    request.headers.get('X-Webhook-Signature'),
    'your-secret'
)

PHP

function verifyWebhook($payload, $signature, $secret) {
    $expectedSignature = 'sha256=' . hash_hmac(
        'sha256', 
        $payload, 
        $secret
    );
    
    return hash_equals($signature, $expectedSignature);
}

// Usage
$isValid = verifyWebhook(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'],
    'your-secret'
);