> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks for real-time updates

> Get real-time updates from OTO when an order arrives, its status changes or a shipment cannot be created, instead of polling the API, and set one up.

Webhooks are how OTO tells your systems that something happened, instead of your systems asking repeatedly whether anything has.

## The three events

| Type | Fires when | Typical consumer |
| - | - | - |
| `orderStatus` | An order's status changes. | Your storefront, ERP or customer-service tool. |
| `shipmentError` | A shipment could not be created with the carrier. | Whatever alerts a human. This is the silent failure. |
| `newOrders` | An order arrives in OTO. | A separate WMS that needs to create it. |

## Setting one up

Register a URL at **Settings → Developers → Webhooks**, or through `POST /rest/v2/webhook`. You choose the method, the event type, an authorization key and a secret; every payload is signed with **HMAC-SHA256** so your endpoint can prove it came from OTO.

Full payloads, the signature scheme and the rules for building an endpoint that survives duplicates and out-of-order delivery are in [Webhook events](https://docs.tryoto.com/developers/webhook-events.md).

> [!WARNING]
>
> **Verify the signature — the URL is not a secret**
>
> Anyone who learns your webhook URL can post to it. Without verification, they can tell your system an order was delivered.
>
> Recompute the HMAC, compare in constant time, and reject stale timestamps.

## The alternative, and why it does not scale

You can poll `orderStatus` on a timer instead, and on day one it works with no endpoint to host. At volume it means thousands of calls to learn that nothing changed, and the one status you needed arrives up to a polling interval late.

## Related

* [Webhook events](https://docs.tryoto.com/developers/webhook-events.md) — payloads and verification.
* [Collaboration & notifications](https://docs.tryoto.com/platform/collaboration-and-notifications.md) — the same events, sent to people instead.
* [Status and tracking updates](https://docs.tryoto.com/modules/sales-channels/updates.md) — the same events, pushed to a sales channel.


## Related topics

- [Create shipments, print labels and track parcels](https://docs.tryoto.com/modules/shipping-management/shipping-and-tracking.md)
- [Receiving and inspecting returns](https://docs.tryoto.com/modules/return-management/returns-receiving.md)
- [Platform architecture](https://docs.tryoto.com/get-started/architecture.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.