Webhook Notifications

Webhooks allow you to receive real-time notifications about important events in your Cerebrum integration. When specific events occur, we'll send an HTTP POST request to your configured postbackWebhookUrl with event details.

Webhook Schema

All webhook notifications follow a standard schema. An example is outlined here:

{
  "id": "ORD-6sdubvu6lmt6",
  "idType": "order",
  "additionalMetadata": {
    "customerName": "John Doe",
    "customerEmail": "[email protected]"
  },
  "event": "ORDER_SCORE_CHANGE",
  "eventDate": "2024-10-09T14:30:45.123Z",
  "svixAppId": "app_2hEDkP8xQLm5J6fN3vR7"
}

Visit here to see the full JSON Schema.

Webhook Event Types

Your webhook endpoint will receive notifications for the following events:

Order Events

• ORDER_STATUS_CHANGE - Triggered when an order's status changes
• ORDER_SCORE_CHANGE - Triggered when an order's score is updated
• ORDER_CUSTOM_SCORE_CHANGE - Triggered when an order's custom score is modified
• ORDER_DISPUTE_RESOLVED - Triggered when a dispute on an order has been resolved

Voucher Events

• VOUCHER_REDEEMED - Triggered when a voucher is successfully redeemed
• VOUCHER_EXPIRED - Triggered when a voucher reaches its expiration date

Delivery and Retry Policy

We will only notify your postbackWebhookUrl when the events listed above occur. If your webhook endpoint is not responding, we will retry the delivery several times before eventually dropping the notification.

Retry Schedule

Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (again, in addition to the previous attempt)

Best Practices

Please ensure that your infrastructure to receive webhooks is robust and can handle all possible webhook events and error scenarios. Be sure to implement proper error handling logic, and always validate the data you receive from us against the provided HMAC signatures.

Webhook Validation

To ensure the authenticity and integrity of webhook requests, all webhooks include cryptographic signatures that you should validate.

How to Validate

• Each webhook has a unique webhook secret. You can obtain the webhook secret from the Svix Portal access provided to you. Make sure not to commit this to a version control system.
• Each webhook request includes the following Svix headers:
  • svix-id - Unique identifier for the webhook message
  • svix-signature - HMAC signature for validation
  • svix-timestamp - Timestamp when the webhook was sent

Validation Methods

Option 1: Using the Svix SDK (Recommended)

You can use the Svix SDK to validate webhook requests in your preferred programming language. Follow this guide: Webhook Validation Guide.

Option 2: Manual Verification

If you prefer not to use the Svix SDK, you can manually verify the request using HMAC with SHA-256 by following this guide: Manual Verification Guide.

Webhook Response Requirements

For a webhook delivery to be considered successful, your endpoint must:

• Return an HTTP 2xx status code (200-299 range)
  • We recommend using 200 OK or 204 No Content
  • Any 2xx status code will mark the delivery as successful
• Respond within 30 seconds
  • Webhooks that timeout will be retried according to the retry schedule
• Response body is optional
  • The response body content is ignored - you can return an empty response
  • There are no specific JSON or text requirements for the response body

Important: Any non-2xx status code (including 3xx redirects, 4xx client errors, and 5xx server errors) will trigger a retry according to the schedule above.

Example Successful Responses

// Minimal successful response
HTTP/1.1 200 OK

// With optional body (content is ignored)
HTTP/1.1 200 OK
Content-Type: application/json

{"status": "received"}

// No content response
HTTP/1.1 204 No Content