Webhook Responses

How webhooks are signed, retried, and what payloads look like.

Before you begin

Before you can receive webhook events, you must first generate an API key, which is required to create and manage webhooks using the Bookvault API.

1. Generate an API Key

Generate a BookVAULT API key from the portal Apps page.

→

Once you have obtained an API key, you can use it to create webhook subscriptions and begin receiving event notifications.

Overview

As part of the Bookvault API, you can configure webhooks to send a request to your chosen URL whenever a particular event occurs. Each event is defined by a corresponding webhook topic.

Available Topics

Subscribe to one or more topics depending on the events your integration needs to react to.

ORDER_CREATED
Triggered when a new order is created in the Bookvault system.
ORDER_ACKNOWLEDGED
Triggered when an order has been acknowledged and accepted for processing.
ORDER_SENTTOPRINT
Triggered when an order has been sent to be printed
ORDER_PRINTED
Triggered when printing of the order has been completed.
ORDER_SHIPPED
Triggered when the order has been dispatched and shipment tracking information is available.

Payload Structure

Each webhook request contains a JSON payload with a consistent top-level structure. The data object varies by topic.

{
    "eventId": "string",
    "topic": "WebhookTopic",
    "timestamp": "ISO-8601 (UTC)",
    "data": {
        // topic-specific fields
    }
}

Payloads

Each webhook topic sends a separate payload containing information relevant to that topic. Click a topic below to view an example.

Example payload

{
    "eventId": "evt_123",
    "topic": "ORDER_CREATED",
    "timestamp": "2026-02-25T12:00:00Z",
    "data": {
        "podRef": "100001",
        "dateCreated": "2026-02-25T11:58:00Z",
        "totalItems": 2
    }
}

Example payload

{
    "eventId": "evt_124",
    "topic": "ORDER_ACKNOWLEDGED",
    "timestamp": "2026-02-25T12:05:00Z",
    "data": {
        "podRef": "100001",
        "dateAcknowledged": "2026-02-25T12:04:20Z"
    }
}

Example payload

{
    "eventId": "evt_125",
    "topic": "ORDER_SENTTOPRINT",
    "timestamp": "2026-02-25T12:10:00Z",
    "data": {
        "podRef": "100001",
        "dateSentToPrint": "2026-02-25T12:09:30Z"
    }
}

Example payload

{
    "eventId": "evt_126",
    "topic": "ORDER_PRINTED",
    "timestamp": "2026-02-25T13:20:00Z",
    "data": {
        "podRef": "100001",
        "datePrinted": "2026-02-25T13:18:45Z",
        "totalPrinted": 2
    }
}

Example payload

{
    "eventId": "evt_127",
    "topic": "ORDER_SHIPPED",
    "timestamp": "2026-02-25T15:35:00Z",
    "data": {
        "podRef": "100001",
        "dateShipped": "2026-02-25T15:34:10Z",
        "carrierName": "Royal Mail",
        "trackingNumber": "TRK123456789",
        "trackingUrl": "https://tracking.example.com/TRK123456789"
    }
}

Webhook Security

To help verify authenticity, Bookvault includes a set of headers with every webhook request:

Header	Description
`X-Webhook-Signature`	A hash signature used to ensure the authenticity of the request.
`X-Webhook-Timestamp`	A UTC timestamp of when the request was sent.
`X-Webhook-Id`	The ID of the webhook, obtained when it is created.

Signing Secret

Each webhook has its own unique signing secret, which is used to sign the events we send to your endpoint. The secret is returned in the response when you first create a webhook via POST /webhook, so please store it securely.

If you need to retrieve the signing secret again at any point, you can request it for a specific webhook using GET /webhook/secret/{ID}.

Signature Verification

The value of X-Webhook-Signature is an HMAC-SHA256 hash of the entire raw payload body, keyed using the webhook's signing secret and Base64-encoded. To verify a request, compute the HMAC-SHA256 of the raw request body using your signing secret and confirm it matches the X-Webhook-Signature header. This confirms the webhook originated from Bookvault and that the payload has not been modified in transit.

Webhook Retries

If your endpoint does not successfully process a webhook request, Bookvault will automatically retry delivery using an exponential backoff strategy. This helps ensure reliable delivery while avoiding excessive retry attempts.

A webhook delivery is considered successful when your endpoint returns a 2xx HTTP status code. Any other response (including timeouts, network failures, or non-2xx status codes) will result in the webhook being retried.

Retry Schedule

Retries are scheduled using exponential backoff, starting at 15 minutes and doubling each time, up to a maximum delay of 4 hours.

Attempt	Delay Before Retry	Example Timeline
1	Immediate	12:00
2	15 minutes	12:15
3	30 minutes	12:45
4	60 minutes	13:45
5	120 minutes	15:45
6+	Maximum 240 minutes (4 hours)	Capped at 4-hour intervals

How Exponential Backoff Works

Each retry delay doubles relative to the previous attempt, starting from 15 minutes, until the maximum delay of 4 hours is reached. This approach balances reliability with system stability.

Attempt 1: immediate
Attempt 2: +15 minutes
Attempt 3: +30 minutes
Attempt 4: +60 minutes
Attempt 5: +120 minutes
Attempt 6+: +240 minutes (maximum)