Webhook Integration Guide

Webhooks let you receive an instant notification whenever someone signs up for your waitlist. When a new lead subscribes, Waitlistly sends a POST request to a URL you specify, containing the lead's details. This lets you connect your waitlist to tools like Zapier, Make, Slack, n8n, or your own backend API.

1Go to Your Project Settings

Open your Dashboard, select your project, and navigate to the Webhook tab (or find the "Webhook Integration" section in your project settings).

2Enter Your Webhook URL

Paste the URL where you want to receive lead data. This is typically a URL provided by your automation tool or your own API endpoint.

3Set a Secret Key (Optional)

If you want to verify that webhook requests are genuinely from Waitlistly, add a secret key. This enables HMAC-SHA256 signature verification. You can use any random string — the longer, the better.

4Enable and Test

Toggle the webhook on, save your settings, then click "Test Webhook" to send a sample request to your URL. The test payload uses dummy data (email: test@example.com) so you can verify everything works.

Payload Reference

Every webhook request is a POST with a JSON body. Here's the full structure:

{
  "event": "lead.created",
  "timestamp": "2026-01-28T14:30:00.000Z",
  "data": {
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1234567890",
    "customAnswer": "Referral",
    "referralCode": "abc12345",
    "referredBy": "xyz67890",
    "queuePosition": 5,
    "source": "landing_page"
  },
  "project": {
    "id": "project-uuid",
    "name": "My Startup",
    "subdomain": "mystartup",
    "url": "https://mystartup.waitlistly.live"
  }
}

HTTP Headers

The following headers are included with every webhook request:

Verifying Webhook Signatures

If you set a secret key, every request includes an X-Webhook-Signature header. To verify a request is genuinely from Waitlistly, compute the HMAC-SHA256 of the raw request body using your secret and compare it to the header value.

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express route handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifySignature(
    JSON.stringify(req.body),
    signature,
    'your-secret-key'
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the lead data
  const { event, data } = req.body;
  console.log('New lead:', data.email);
  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_signature(raw_body: str, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        raw_body.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Integration Examples

Troubleshooting