Features

Webhooks

Webhooks overview

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

Webhooks are available on the Growth 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
Multiple Event Types: Receive notifications for sign-ups, referrals, and milestone achievements
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

Webhook Events

Waitlister supports three webhook event types that you can enable or disable individually.

New Sign-ups

waitlist.signup_created

Triggered when someone joins your waitlist. Use this to sync subscribers to your CRM, send custom welcome emails, or update analytics.

Referrals Completed

waitlist.referral_completed

Triggered when a subscriber successfully refers someone new. Use this to reward top referrers, send thank-you messages, or track viral growth.

Milestones Reached

waitlist.milestone_reached

Triggered when a subscriber reaches a configurable points threshold. Use this to unlock rewards, grant early access, or celebrate achievements with your community.

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
Select which events you want to receive
Configure milestone thresholds (for milestone events)
Test your webhook to make sure it's working correctly

Event Configuration

You can enable or disable each event type independently:

New sign-ups: Always available and enabled by default
Referrals completed: Enable to track when subscribers refer others
Milestones reached: Configure point thresholds (default: 100, 200, 300, 500, 1000 points)

You can add up to 10 custom milestone thresholds to match your reward structure.

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 Payloads

{
  "event": "waitlist.signup_created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "signup_abc123",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "+1 123 4567",
    "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
    }
  }
}

Referral Completed Event

{
  "event": "waitlist.referral_completed",
  "timestamp": "2025-01-15T11:45:00Z",
  "data": {
    "referrer": {
      "id": "signup_abc123",
      "email": "[email protected]",
      "name": "Jane Doe",
      "points": 80,
      "position": 15,
      "total_referrals": 2,
      "referral_code": "happy-star-4f3d"
    },
    "new_signup": {
      "id": "signup_xyz789",
      "email": "[email protected]",
      "name": "Bob Smith",
      "referred_by": "happy-star-4f3d"
    },
    "points_earned": 30,
    "waitlist": {
      "key": "your-waitlist-key"
    }
  }
}

Milestone Reached Event

{
  "event": "waitlist.milestone_reached",
  "timestamp": "2025-01-15T12:00:00Z",
  "data": {
    "subscriber": {
      "id": "signup_abc123",
      "email": "[email protected]",
      "name": "John Doe",
      "points": 100,
      "previous_points": 85,
      "position": 12,
      "referral_code": "happy-star-4f3d"
    },
    "milestone": {
      "points": 100,
      "reached_at": 1642249200000
    },
    "waitlist": {
      "key": "your-waitlist-key"
    }
  }
}

X-Webhook-Signature: sha256=your-computed-signature
X-Waitlister-Event: waitlist.signup_created | waitlist.referral_completed | waitlist.milestone_reached
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'
);

// Handle different event types
const event = req.body.event;
switch (event) {
  case 'waitlist.signup_created':
    // Handle new sign-up
    break;
  case 'waitlist.referral_completed':
    // Handle referral
    break;
  case 'waitlist.milestone_reached':
    // Handle milestone
    break;
}

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

# Handle different event types
event = request.json.get('event')
if event == 'waitlist.signup_created':
    # Handle new sign-up
    pass
elif event == 'waitlist.referral_completed':
    # Handle referral
    pass
elif event == 'waitlist.milestone_reached':
    # Handle milestone
    pass

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

// Handle different event types
$event = json_decode($payload)->event;
switch ($event) {
    case 'waitlist.signup_created':
        // Handle new sign-up
        break;
    case 'waitlist.referral_completed':
        // Handle referral
        break;
    case 'waitlist.milestone_reached':
        // Handle milestone
        break;
}

Use Cases

Reward System Automation

Use milestone webhooks to automatically grant rewards when subscribers reach point thresholds:

100 points: Send exclusive content via email
200 points: Grant early access tier 1
500 points: Unlock beta features
1000 points: Award VIP status

Referral Campaign Tracking

Use referral webhooks to track and incentivize your top advocates:

Send thank-you messages after each successful referral
Award bonus points after 5, 10, or 25 referrals
Identify power users for special outreach
Track referral campaign performance in your analytics

Multi-platform Sync

Use sign-up webhooks to keep your systems in sync:

Add subscribers to your email marketing platform
Update your CRM with new leads
Post to Slack when someone joins
Sync to your data warehouse for analytics

Troubleshooting

Common Issues

Webhook not receiving requests

Verify your URL is publicly accessible and uses HTTPS
Check your firewall settings allow incoming requests
Ensure your endpoint returns a 2xx status code
Verify the event type is enabled in your webhook configuration

Intermittent failures

Check your server's response time (should be under 15 seconds)
Verify your endpoint can handle concurrent requests
Review error logs for specific failure reasons

Signature verification failing

Ensure you're using the exact secret configured in Waitlister
Verify you're computing the HMAC using the raw request body
Check that your secret doesn't contain extra whitespace

Not receiving specific events

Check that the event type is enabled in your webhook configuration
For milestone events, verify your milestones are configured correctly
For referral events, ensure your referral program is enabled

Webhook Status

Webhooks have three possible statuses.

Active: Webhook is configured and working correctly
Inactive: Webhook failed its last test or delivery
Disabled: Webhook was automatically disabled due to repeated failures

Webhooks are automatically disabled after 10 consecutive failures to prevent spam and protect your endpoint.

Re-enabling Disabled Webhooks

If your webhook was automatically disabled, follow these steps.

Fix the issue causing failures (check logs for error details)
Go to webhook configuration page
Click "Re-enable webhook" in the status warning
Test the webhook to verify it's working

Help and Support

Need assistance with webhooks? We're here to help.

Contact us via the public contact form
Access the "Help" page in your account dashboard
Check the webhook logs for detailed error information

Documentation