> For the complete documentation index, see [llms.txt](https://docs.optondemand.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optondemand.com/integrations-and-apps/rest-api/api-structure/webhooks.md).

# Webhooks

Register your system to receive notifications

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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.