Skip to main content
A webhook turns the integration around. Instead of asking OTO what happened every few minutes, you host a URL and OTO tells you.

​
The three event types

Subscribe to shipmentError even if you subscribe to nothing elseA failed booking is silent by nature: the order does not move, and no status change fires because nothing changed.The payload names the cause — an errorCode, and the carrier’s own words in deliveryCompanyResponse, typically something like a missing city or postcode. Those are fixable in seconds if someone knows, and invisible for days if nobody does.

​
Registering one

POST /rest/v2/webhook Starter+ GET lists your subscriptions, PUT updates one by id, and DELETE removes it. All at the same path.

​
What arrives

An orderStatus payload carries the order and its new state, the carrier and driver where there is one, the tracking number and URL, a link to the AWB, and a timestamp in UTC. A shipmentError payload carries the orderId, an errorCode, OTO’s errorMessage and the carrier’s raw deliveryCompanyResponse. A newOrders payload carries the whole order — address, items, weight, totals, payment method, sales channel and warehouse.

​
Verifying that it came from OTO

Every payload carries a signature: an HMAC-SHA256 over a colon-joined string, base64 encoded, using the secretKey you registered.
Verify the signature, and reject stale timestampsYour webhook URL is reachable by anyone who learns it. Without verification, anyone who does can tell your system an order was delivered.Recompute the HMAC over the signed string and compare it with a constant-time comparison. Then check the timestamp is recent — a valid signature on an old payload is a replay, and marking yesterday’s order delivered again is the mildest thing it can do.

​
Building an endpoint that holds up

  • Answer immediately. Return 200 as soon as you have the payload, and do the work afterwards. A slow endpoint looks like a broken one.
  • Expect duplicates. Deliveries can repeat. Key on orderId plus status plus timestamp and make reprocessing harmless.
  • Expect them out of order. Network timing does not respect your state machine. Never move an order backwards because an older event arrived late.
  • Log the raw body before parsing it. When an integration misbehaves at 2am, the payload you did not keep is the one you needed.