Set up webhooks

Overview

A webhook is a message O2M sends to your server the moment something happens, so you do not need to keep asking.

Before you begin

You are an admin, or your role includes See and manage API keys, API logs and webhooks.
Your server has a public HTTPS address.

Add an address

Figure 22.1 Settings → API and Webhooks → Webhooks, with your addresses and their deliveries.

1Open Settings → API and Webhooks → Webhooks and click Add an address.
2Enter your server's address, and tick the events under Events to send.
3Copy the signing secret. It is shown only once.
4Click Send a test to check your server receives it.

If you lose the signing secret, click New secret to replace it. The old one stops working straight away, so update your server at the same time.

Rules for an address

It must start with https:// and be reachable from the internet.
It cannot contain a user name or password.
It can be up to 500 characters long.
A company can have 10 addresses.
An address for a 3PL client receives only events about that client's items and orders.

What O2M sends

Each event is a JSON POST to your address.

HTTP

POST /o2m-webhook HTTP/1.1
Content-Type: application/json
User-Agent: O2M-Webhooks/1
X-O2M-Event: stock.changed
X-O2M-Delivery: 0b1f6c1e-6c55-4d0e-9d8a-2f4c3a1e7b90
X-O2M-Signature: t=1790000000,v1=5f2c9a…

Body

{
  "id": "0b1f6c1e-6c55-4d0e-9d8a-2f4c3a1e7b90",
  "event": "stock.changed",
  "created_at": "2026-10-02T10:00:00.000Z",
  "company_id": "12",
  "data": {
    "sku": "MUG-BLUE",
    "sellable": 13,
    "reason": "stock_decreased"
  }
}

Field	Type	Description
`id`	string	The event's ID. It stays the same on every retry.
`event`	string	What happened. See Events.
`created_at`	string	When it happened.
`company_id`	string	Your company's reference in O2M.
`data`	object	The details, which depend on the event.

Headers

Header	Meaning
`X-O2M-Event`	The event's name.
`X-O2M-Delivery`	The event's ID. Use it to ignore repeats.
`X-O2M-Signature`	Proves the message came from O2M. See Verify signatures.

If you cannot add an address

Message	What to do
Enter the full address, for example https://example.com/o2m-webhook	Enter a complete address.
The address must start with https://	Serve your endpoint over HTTPS.
The address must be reachable from the internet	Use a public address, not a private network.
The address cannot carry a user name or password	Remove them from the address.
The address is too long	Use up to 500 characters.
Choose at least one event	Tick an event.
A company can have 10 webhook addresses. Remove one you no longer use.	Remove an address.