Prerequisites

• An active SCALAR integrator account
• A secure HTTPS webhook endpoint that can receive POST requests
• Ability to process JSON request bodies
• Webhook endpoint should respond within 3-5 seconds
• Backend service to handle asynchronous event processing

Step-by-Step Setup

Step 1: Prepare Your Webhook Endpoint

Your webhook endpoint must:

1. Accept HTTP POST requests with Content-Type: application/json
2. Validate HMAC signatures to verify requests from SCALAR
3. Return appropriate HTTP status codes (200 for success, 5xx for server errors)
4. Support asynchronous processing to respond quickly
5. Whitelist SCALAR IP addresses (see section on IP Whitelisting)

Example endpoint implementation concepts:

1. Implement a POST handler at your specified URL
2. Validate the HMAC signature from the X-SCALAR-SIGNATURE header
3. Immediately return 200 OK to acknowledge receipt
4. Process events asynchronously in the background
5. Implement idempotent processing to handle retries

Step 2: Create a Webhook Subscription

1. Log into SCALAR Web portal
2. Navigate to Datahub Subscriptions
3. Click Create Subscription
4. Fill in subscription details:
   1. Subscription Name: Descriptive name for your subscription
   2. Subscription Method: Select "Webhook"
   3. Webhook URL: Your HTTPS endpoint URL (must be publicly accessible)
   4. Webhook Secret: Generate a secure secret for HMAC validation
5. Select Event Types:
   1. Choose event groups (e.g., sensors, track & trace, asset)
   2. Select specific events within those groups
   3. Configure event versions if needed
6. Configure Delivery Settings:
   1. Batch Size: Number of events per batch (max 500)
   2. Maxmum Waiting Time: Maximum wait time before sending batch (milliseconds)
   3. Overflow Protection: Enable to buffer data during high-volume periods
7. Add Custom Headers (Optional):
   1. Add up to 5 custom headers required by your system
   2. Useful for authorization tokens, correlation IDs, or system identifiers

Step 3: Test Your Webhook

1. In the subscription details, click Test Connection
2. SCALAR sends a test payload to your webhook endpoint
3. Verify your endpoint receives and processes the test data
4. Check that you receive a successful response notification
5. Click Save to create the subscription

Step 4: Activate and Monitor

1. Once testing is successful, save the subscription
2. SCALAR begins sending live event data to your endpoint
3. Monitor the Webhook Developer Metrics for delivery status and metrics
4. Review notifications for any configuration issues