Webhook Delivery Process

All webhook notifications follow a standard schema, which is outlined here:

{
    // id of a resource for which event happened
    id: "string";
    // resource type
    idType: "order" | "invite" | "beamInput";
    // this will be the same json object which was passed when creating voucher/order
    additionalMetadata: {};
    // event name
    event: "ORDER_STATUS_CHANGE" | "ORDER_SCORE_CHANGE" | "VOUCHER_REDEEMED" | "BEAM_INPUT_CREATED";
    // date at which event happened
    eventDate: "DateTime";
    svixAppId: "ID of Svix App";
}

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.