Webhook Endpoint Implementation Guide

Basic Implementation Pattern

Your webhook endpoint should follow this pattern:

{
  "implementation_pattern": {
    "step1": {
      "action": "Receive HTTPS POST request",
      "details": "Extract headers and body"
    },
    "step2": {
      "action": "Validate HMAC signature",
      "details": "Compare X-Webhook-Signature with calculated hash"
    },
    "step3": {
      "action": "Check for duplicates",
      "details": "Query database for eventBatchId"
    },
    "step4": {
      "action": "Return 200 OK immediately",
      "details": "Respond quickly to SCALAR"
    },
    "step5": {
      "action": "Queue events for processing",
      "details": "Add to message queue or background job"
    },
    "step6": {
      "action": "Process events asynchronously",
      "details": "Parse, validate, and store events"
    },
    "step7": {
      "action": "Handle errors gracefully",
      "details": "Log failures, retry if needed"
    }
  }
}

Response Handler

Your endpoint must respond appropriately:

  • Success (200): Event processed successfully
  • Server Error (5xx): Temporary failure, SCALAR will retry
  • Client Error (4xx): Configuration issue, SCALAR will not retry
  • Timeout: No response within 3-5 seconds, SCALAR will retry