Documentation
Start typing to search…

Webhook Delivery Process

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.

We will only notify your postbackWebhookUrl upon specific changes to the status of your created invite(s) or order(s), for example when the order is marked complete and/or scored. If the webhook URL is not responding, we will retry the delivery several times before eventually dropping the notification.

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 (in addition to the previous)

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

  • 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
    • svix-signature
    • svix-timestamp
  • You can use the Svix SDK to validate webhook requests in your preferred programming language. Follow this guide: Webhook Validation Guide.
  • 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.

If you do not have infrastructure set up to receive and manage incoming webhooks, you may want to consider using a webhook management solution like Hookdeck.io. Hookdeck.io is a third-party service that allows you to easily manage incoming webhooks and provides features including validation, retries, and event logging.

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

Updated 11 days ago