Webhooks let SKULabs push a notification to your own server the moment something happens in your account — an order ships, a batch is created, a purchase order is received. Instead of polling the SKULabs API on a timer, your endpoint gets called.

This guide covers every available event, the exact payload you will receive, how headers and authentication work, and how to inspect and debug a live webhook.

You need three things:

Go to Settings → Advanced → API, scroll to the Webhooks section, and click Add webhook.

Give it up to 10 minutes. SKULabs caches the list of active subscriptions per event type. A newly added webhook can take up to 10 minutes to begin firing. Editing an existing webhook takes effect immediately.

One webhook subscribes to one event type. To listen for several events, create several webhooks — they can all point at the same URL, and you can tell them apart using the type field in the payload.

Note that the status names contain spaces, not underscores — the event type is order.status.partially shipped, not order.status.partially_shipped.

Tip: subscribe to order.status instead of the individual statuses. One subscription covers every transition, and you switch on data.status in your own code. This is fewer webhooks to manage and it will not miss statuses that are not in the dropdown, such as archived.

Two dropdown options behave differently than their labels suggest.

For both cases, subscribe to purchase_order.status and read data.status — that catch-all fires on every transition, including edits.

Some earlier API reference examples mentioned the event names below. These are not currently available — a webhook using one will save, but it will never be called:

item.updated, item.inventory, order.shipped, order.tracking, order.tags, shipment.created, shipment.voided, transfer_order.*

We add events on request. If you need one that is not in the tables above, contact support and tell us what you are trying to build.

SKULabs sends a JSON body with exactly two top-level keys, type and data:

There is no body. type and data are appended to the query string, and data is a URL-encoded JSON string that you will need to parse:

Any query parameters already present in your configured URL are preserved.

Your endpoint is a public URL, so you should assume anyone can send requests to it and verify every one before acting on it. SKULabs authenticates itself using the headers you configure, so treat that header as a shared secret.

Generate a long random secret and put it in the Headers (JSON) field:

Then reject any request to your endpoint that does not carry it:

Guidelines:

Return any 2xx status code. The response body is ignored.

Anything else — 3xx, 4xx, 5xx, a connection error, or a timeout — is treated as a failure and queued for retry.

Acknowledge quickly. Do the real work in a background job rather than holding the connection open while you write to your database or call another API.

A failed delivery is retried with a growing backoff of attempt² × 10 minutes, capped at 72 hours:

A delivery is abandoned after 30 days of unsuccessful retries.

These status codes mean the request will never succeed, so SKULabs stops immediately and disables the webhook:

400, 404, 405, 410, 422

A 404 is the most common one to hit by accident. If your endpoint is not deployed yet, or the path has a typo, the webhook is disabled on the very first delivery.

To avoid hammering an endpoint that is already struggling, SKULabs widens the gap between attempts further once a webhook has accumulated a long run of failures. A webhook that has been failing for a while may be retried only a few times a day until it succeeds again.

A webhook is automatically set to inactive when both are true:

When this happens we email your account's billing contact with the webhook name, type, URL, and method. All of its pending deliveries are cancelled.

To re-enable it: fix your endpoint, then go to Settings → Advanced → API, click the pencil icon on the webhook, check Active, and save. This clears the disabled state and resets the failure count.

The fastest way to find out exactly what an event sends:

Once you know the shape, point the webhook at your real endpoint.

The webhook table at Settings → Advanced → API has a Last Used column showing:

A webhook with a Failed Count climbing and no recent success means your endpoint is rejecting or timing out.

Go to Settings → Advanced → Sync Reports and look for entries of type webhook. Each failure records the webhook name, event type, HTTP status returned, target URL, and attempt number — for example:

Webhook "Ship notifications to ERP" (order.status.shipped) failed with HTTP 500 at https://api.yourcompany.com/hooks/skulabs — attempt #3.

This is the first place to look when you know an event happened but nothing arrived.

Fields with no value are omitted rather than sent as null, so treat every field as optional in your parser.

The payload does not include line items. If you need them, call the order API using store_id and order_number.

order_number is populated only for dropship POs, where it is the sales order the PO was raised for. type on each item is Item or Kit.

items is the full list after the edit, in the same shape as the created event. log is a human-readable list of what changed.

This event fires once per receiving action, and the payload differs slightly depending on what was received.

Receiving an item or a kit — items contains only the line that was received, with a received running total:

store_id and order_number are included when a kit is received, and omitted when a plain item is received.

Receiving a custom item — there is no items array. A single custom_item object is sent instead:

Handle both shapes: check for items first, then fall back to custom_item.

Every item on the PO is included, each with its final received quantity.

Everything in the UI is available on the API, which is useful for subscribing to purchase_order.status.update since it is not in the dropdown.

Create: POST /webhook/add_handler

List: GET /webhook/get_handlers — returns every webhook on the account, including last_success, last_failed, and failed_count.

Update: POST /webhook/update_handler with { "_id": "...", "update": { ... } }. Setting active: true also clears the automatically-disabled state.

Delete: POST /webhook/remove_handler with { "_id": "..." }.

Copy event names exactly from the tables above. An event name that does not match a supported type saves successfully but never fires, which is easy to mistake for a broken endpoint.

Contact support with:

We can look up the delivery attempts on our side and tell you exactly what happened.