Webhooks
When your API source is set up we ask you for a webhook delivery URL. When one of your Bob Shop orders is paid, we POST it to that URL.
This is the only request we make to your system. We do not fetch products from you, and we do not send product, price or stock updates.
Events
| Event | Fires when |
|---|---|
| Order created | One of your Bob Shop orders is paid. See the Order created page for the payload. |
There is no order-status or tracking API
This API manages listings, not orders. There is no endpoint to fetch orders,
and no way to send an order's status or a tracking number back to us.
sellersOrderStatus in the payload is informational only. Order status and
tracking are handled in the Bob Shop seller portal.
Why webhooks matter for your stock
We do not adjust the stock you sent us when an item sells. Your next product update is taken as is, so a pre-sale quantity puts the old number back on the listing and the item can oversell.
After each order, reduce the stock in your own system and send us the new quantity for the sold variants with Create or update a product. Workflow, step 5, has the sequence.
Securing your endpoint
These requests are not signed and carry no authentication. Signed webhooks are on our roadmap. Until then, use the measures below. The headers we send are:
| Header | Value |
|---|---|
User-Agent |
Bob Shop Tools/1.0 |
Content-Type |
application/json |
X-Request-ID |
A UUID for the whole operation. |
bobshop-tools-req-id |
A UUID for this delivery attempt. |
Quote either ID header when reporting a problem to us.
- Treat the delivery URL as a secret: a long, unguessable path, not published.
- Treat the contents as untrusted until matched against your own records.
- Our requests come from one fixed IP address per environment. Allow-list it as defence in depth, not as proof on its own:
| Environment | IP address |
|---|---|
| Production | 13.245.115.171 |
| Sandbox (QA) | 13.247.220.131 |
What we expect back
Respond 200 within 2 minutes. Any status from 200 to 399 counts as
success, so do not answer with a redirect: a 3xx means we will not send the
order again. After 2 minutes we give up and count it as a failure. Acknowledge
first, then process.
Retries are limited. A 4xx, a 5xx or a timeout is retried, up to 4
attempts in total, about 6 minutes apart. After that the delivery is set
aside and not retried, so a handler that is down for more than about 20
minutes misses orders. There is no replay endpoint:
contact support to have set-aside deliveries re-sent. Reconcile against the
webhooks you did receive so a gap is easy to spot.
Expect repeats. Retries can deliver the same order more than once, and if
order pushing is also switched on for your API channel in Bob Sync, every
order is delivered twice. Key on orderId and ignore duplicates.
The envelope
Every webhook is wrapped in an envelope. The order itself is under
webhook_payload, alongside the channel_id it relates to. Read
webhook_payload, not the top level:
{
"channel_id": 1234,
"webhook_payload": { ... }
}
See the Order created page for the payload.