Webhooks API

The Webhooks API allows you to receive real-time notifications when important events occur in Scalar. This is ideal for syncing data with external systems or triggering custom workflows.

Overview

When an event occurs, Scalar sends an HTTP POST request to your configured URL. Each request includes security headers and a JSON payload.

Headers

Header	Description
X-Scalar-Signature	HMAC-SHA256 signature for payload verification.
X-Scalar-Event	The event type (e.g. `idea.created`).
X-Scalar-Delivery-Id	Unique identifier for this specific delivery attempt.

Available event types

Event	Description
idea.created	A new idea has been submitted and approved.
idea.status_changed	An idea's status has been updated.
idea.voted	An idea has received a new upvote.
survey.response_created	A new response to a survey has been submitted.
announcement.published	A new announcement has been published.
customer.created	A new customer has been added to your company.
customer.approved	A customer account has been approved.

Configuration

Webhooks are configured in the Scalar dashboard under Settings > Webhooks (located in the API & Integrations section).

Security and verification

To ensure a webhook was sent by Scalar, you should verify the X-Scalar-Signature using your webhook secret.

Signature verification (Python)

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)

Payload format

All webhook payloads follow this consistent structure:

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

Retry behaviour

Scalar automatically retries failed webhook deliveries using exponential backoff:

Attempt	Delay
1	Immediate
2	After 1 minute
3	After 5 minutes
4	After 5 minutes

After 4 failed attempts, the delivery is marked as failed. If an endpoint accumulates 10 consecutive failures across any deliveries, it is automatically disabled to prevent further failed requests.

Best practices

Respond quickly: Return a 2xx status code within 10 seconds.
Be idempotent: Handle duplicate deliveries gracefully using the X-Scalar-Delivery-Id.
Verify signatures: Always check the signature before processing the payload.
Use HTTPS: Your webhook URL must use HTTPS.
Monitor failures: Re-enable disabled endpoints in the dashboard after fixing issues.