# Webhooks

The Webhook API enables developers to subscribe to notifications for changes of selected events. This API allows you to register a webhook to send notifications to any specified URL, update the URL as needed, or unsubscribe from notifications entirely.

All notifications are secured with an **HMAC signature (SHA256)** included in the `X-Signature` header, allowing recipients to verify the authenticity of each message.

The **secretKey** used for generating the HMAC signature is provided in the response upon successful webhook registration.

## Message example 

All messages follow this payload format. The data parameter contains an object with all information about the given entity. For order updates, the format is [Get Order Details](/integrations-and-apps/rest-api/api-structure/orders/get-order-details.md).

```
{
    "event": "ORDER_STATUS_UPDATED",
    "timestamp": "2025-07-08T12:34:56Z",
    "data": {
        ...
    }
}
```

## How to verify message authenticity

By following this process, you ensure that your system only processes verified notifications for any subscribed event and remains secure against tampered or fraudulent requests.

#### 1. Webhook Registration 

Subscribe to new event notifications by using the endpoint [Register new Webhook](/integrations-and-apps/rest-api/api-structure/webhooks/register-new-webhook.md)

**In response, you will receive a secretKey, which you will use to verify the authenticity of each incoming notification.**

#### 2. Receiving Notifications

Whenever the selected event occurs, the system will automatically send a POST request to your specified URL, which includes:

* A JSON payload with the event data
* **The X-Signature HTTP header containing an HMAC-SHA256 signature**

#### 3. Verifying the Signature

To ensure the notification is genuine and unaltered, follow these steps:

* Use the secretKey provided during the webhook registration.
* Compute the HMAC-SHA256 signature using the raw JSON request body.

Example in Node.js using crypto library

```javascript
const crypto = require('crypto');

// secretKey from webhook registration
const hmac = crypto.createHmac('sha256', secretKey);

// rawRequestBody is the original JSON string (raw body of the request)
hmac.update(rawRequestBody);

const computedSignature = hmac.digest('hex');
```

#### 4. Signature Comparison

* Compare your computed computedSignature with the value received in the X-Signature header (specifically the part after sha256=).
* **If both signatures match, you can trust the notification as authentic.**

## Retry mechanism

If a notification cannot be delivered (e.g., due to a 4xx/5xx status code or a timeout), the system will automatically retry sending it using an **exponential backoff strategy** — the delay between attempts doubles each time (1s, 2s, 4s, 8s, etc.) and the **maximum retry window is 24 hours.**

The order of message delivery is guaranteed, ensuring that users receive their messages in the sequence they expect. A recipient will not receive another message for the same event until the previous one has been successfully received.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.optondemand.com/integrations-and-apps/rest-api/api-structure/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.