Setting up webhooks

This guide covers configuring webhooks to receive real-time notifications when events occur in Scalar.

What are webhooks?

Webhooks let you receive HTTP notifications when important events happen:

• A new idea is submitted
• An idea's status changes
• A survey receives a response
• An announcement is published
• A new customer signs up

When an event occurs, Scalar sends an HTTP POST request to your configured URL with event data.

Prerequisites

Webhooks require a subscription add-on. Check your plan in Settings > Billing.

Creating a webhook

1. Go to Settings > Webhooks (in the API & Integrations section)
2. Click Add webhook
3. Enter your endpoint URL (must be HTTPS)
4. (Optional) Add a description
5. Select the events to subscribe to
6. Click Add webhook

Available events

You can subscribe to individual events or select All events to receive notifications for everything.

Payload format

All webhooks use this consistent structure:

{
  "event": "idea.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": 123,
    "slug": "dark-mode-abc123",
    "title": "Dark Mode",
    ...
  }
}

Security headers

Each webhook request includes these headers:

Verifying signatures

Verify that webhooks come from Scalar by checking the signature:

Python example

import hmac
import hashlib
import json

def verify_signature(payload: dict, signature: str, secret: str) -> bool:
    message = json.dumps(payload, separators=(",", ":"), sort_keys=True)
    expected = hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Node.js example

Install the json-stable-stringify package: npm install json-stable-stringify or yarn add json-stable-stringify

const crypto = require('crypto');
const stringify = require('json-stable-stringify');

function verifySignature(payload, signature, secret) {
  // Use a stable stringifier to ensure keys are always in the same order
  const message = stringify(payload);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  const expectedBuffer = Buffer.from(expected);
  const signatureBuffer = Buffer.from(signature);

  if (expectedBuffer.length !== signatureBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(expectedBuffer, signatureBuffer);
}

Testing webhooks

Send a test payload to verify your endpoint:

1. Go to Settings > Webhooks
2. Find your webhook
3. Click Test
4. Check your endpoint received the test payload

Viewing delivery history

Monitor webhook deliveries:

1. Go to Settings > Webhooks
2. View the Recent deliveries section
3. Each delivery shows:
   • Event type
   • Timestamp
   • Response code (200, 500, Timeout, etc.)
   • Success/failure status

Retry behaviour

Scalar automatically retries failed deliveries:

After 4 failed attempts, the delivery is marked as failed.

Automatic disabling

If a webhook endpoint accumulates 10 consecutive failures, it's automatically disabled. Re-enable it in the webhooks settings after fixing the issue.

Best practices

1. Respond quickly: Return a 2xx status code within 10 seconds
2. Be idempotent: Handle duplicate deliveries gracefully using X-Scalar-Delivery-Id
3. Verify signatures: Always check the signature before processing
4. Use HTTPS: Your endpoint URL must use HTTPS
5. Monitor failures: Check delivery history and fix issues promptly

Editing webhooks

1. Go to Settings > Webhooks
2. Find the webhook
3. Click Edit
4. Update the URL, events, or enabled status
5. Click Save changes

Disabling webhooks

To temporarily stop receiving notifications:

1. Go to Settings > Webhooks
2. Click Edit on the webhook
3. Toggle Enabled off
4. Click Save changes

The webhook remains configured but won't receive notifications until re-enabled.

Deleting webhooks

1. Go to Settings > Webhooks
2. Find the webhook
3. Click the delete button
4. Confirm deletion

The webhook stops receiving notifications immediately.

Next steps

• Generating API keys - Set up API access
• Scalar API documentation - Full API reference