Webhooks

A webhook is just a URL of yours that we call when something happens in your workspace — an import finishes, an order comes in, and so on. You register the URL once; we POST each event to it. No polling.

Set one up

Create an endpoint with your API key and tell us which events you care about:

curl https://api.sentralbee.app/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/sentralbee/webhooks",
    "enabled_events": ["import.completed", "import.failed"]
  }'

The URL has to be https. Use ["*"] for enabled_events if you want everything. The response includes a signing secret — copy it now, it’s shown only once. (Lost it? Rotate it from the dashboard or POST /webhooks/{id}/secret/rotate.) Managing webhooks needs a key with the webhook permission (or a full-access key).

What a delivery looks like

Every event we send has the same shape:

{
  "id": "5f0c2a8e-…",
  "type": "import.completed",
  "workspace": "9f1c…",
  "livemode": true,
  "created_at": "2026-06-07T09:02:00Z",
  "data": { "import_id": "…", "status": "completed", "counts": { "products": 100 } }
}

livemode is true for events from your real workspace and false for events from a sandbox — handy for keeping test traffic out of your real processing. Along with three headers:

Webhook-Id — the event id.
Webhook-Timestamp — unix seconds when we signed it.
Webhook-Signature — v1,<hex>.

Check the signature

Before you trust a delivery, verify it came from us. Recompute the signature with your endpoint’s secret and compare:

signed = "{Webhook-Id}.{Webhook-Timestamp}.{raw request body}"
expected = "v1," + hex( HMAC_SHA256(secret, signed) )

Compare expected to the Webhook-Signature header using a constant-time comparison. Reject the request if they don’t match, or if the timestamp is more than a few minutes old.

Reply quickly, and we’ll retry

Return any 2xx within 20 seconds and we consider it delivered. Return anything else (or time out) and we retry with backoff — right away, then 1m, 5m, 30m, 2h and 6h later, six attempts over about 8½ hours. So:

Do the slow work after you respond, not before. Acknowledge fast.
Expect the same event more than once. Use the event id to de-duplicate.

You can see every attempt under GET /webhooks/{id}/deliveries, inspect one with its request and response bodies, and re-send any of them.

Test it

POST /webhooks/{id}/ping sends a webhook.ping event to your endpoint so you can confirm your handler and signature check work before real events flow. GET /webhooks/event-types returns the live list. Put any of these names in enabled_events, or use ["*"] for all of them.

Products

Event	Fires when
`product.created`	A product is created.
`product.updated`	Any field on a product changes.
`product.published`	A product transitions into ACTIVE — i.e. becomes visible on the storefront (products default to hidden).
`product.deleted`	A product is deleted.

Collections

Event	Fires when
`collection.created`	A collection is created.
`collection.updated`	A collection’s details change.
`collection.deleted`	A collection is deleted.

Products joining or leaving a collection — including automatic changes to a rule-driven collection — do not emit a collection event; only the collection entity itself does. To track membership, read GET /collections/{handle}/products. A collection event’s data:

{
  "id": "c1a3…",
  "name": "Summer Sale",
  "handle": "summer-sale",
  "published": true,
  "sort_order": "MANUAL",
  "membership_type": "SMART",
  "description": "Warm-weather picks"
}

Bundles

Event	Fires when
`bundle.created`	A bundle is created.
`bundle.updated`	A bundle’s details, price or status change, or a product is added to, changed in or removed from it.
`bundle.deleted`	A bundle is deleted. Orders that sold it keep their lines.

A bundle’s members are its definition, so member changes are a bundle.updated — its data always carries the full member list. Prices and stock move without a bundle event (they belong to the member products); refetch GET /bundles/{bundle} for those.

{
  "id": "b7e2…",
  "name": "Alara Set",
  "slug": "alara-set",
  "status": "ACTIVE",
  "price": null,
  "item_count": 2,
  "items": [
    { "id": "…", "product": "…", "product_variant": null, "quantity": 1, "position": 0 },
    { "id": "…", "product": "…", "product_variant": "…", "quantity": 1, "position": 1 }
  ],
  "updated_at": "2026-09-11T10:00:00Z"
}

price is a per-currency map in minor units ({"NGN": 34000000}); null means the bundle charges the plain sum of its members. product_variant is set only when the merchant pinned one.

Orders

Event	Fires when
`order.created`	An order (cart) row is created.
`order.updated`	An order changes — the payload carries its current state.
`order.paid`	An order transitions into fully PAID.
`order.payment_recorded`	A payment (partial or full) is recorded against an order.
`order.production_stage_changed`	An order item moves to a new production stage.

order.created fires at the cart stage. If you only care about real orders, watch status on order.updated rather than acting on every order.created.

Fulfillments

Event	Fires when
`fulfillment.created`	Items of an order are packed into a shipment.
`fulfillment.updated`	A shipment’s status or tracking changes — shipped, delivered, exception or cancelled.

{
  "fulfillment_id": "…",
  "order_id": "…",
  "status": "SHIPPED",
  "carrier": "FEDEX",
  "service_name": "FedEx Ground",
  "tracking_number": "7946…",
  "tracking_url": "https://…"
}

Customers

Event	Fires when
`customer.created`	A customer is created — from the dashboard, a storefront checkout, an import or a sync.
`customer.updated`	A customer’s details change.

{
  "id": "…",
  "firstname": "Amina",
  "lastname": "Bello",
  "email": "[email protected]",
  "phone": "+2348000000000",
  "created_at": "2026-09-11T10:00:00Z",
  "updated_at": "2026-09-11T10:05:00Z"
}

Materials and supplies

These, and every section below, fire from the dashboard, the Bee and the API alike. A bulk import reports once, through import.completed, instead of an event per row.

Event	Fires when
`component.created`	A material is created.
`component.updated`	A material’s details change. Stock used up by production moves no event.
`component.deleted`	A material is deleted.
`component_supply.created`	A supply — one received batch of a material — is recorded.
`component_supply.updated`	A supply is edited.
`component_supply.deleted`	A supply is deleted.

{
  "id": "…",
  "component_id": "…",
  "sku": "LIN-0924",
  "cost": { "NGN": 4500000 },
  "supplied_stock": 30,
  "available_stock": 30,
  "supplier_id": "…",
  "supplier_order_number": "PO-118",
  "date_of_supply": "2026-09-11T00:00:00Z",
  "best_before": null
}

A component.* event carries id, name, category, status, unit_of_measure, track_stock and available_stock.

Suppliers

Event	Fires when
`supplier.created`	A supplier is created.
`supplier.updated`	A supplier’s details change.
`supplier.deleted`	A supplier is deleted.

data carries id, name, email, telephone and roles.

Product categories and tags

Event	Fires when
`product_category.created`	A category is created.
`product_category.updated`	A category’s name, slug, parent or position changes.
`product_category.deleted`	A category is deleted.
`tag.created`	A tag joins the workspace’s tag list — including when a product form or import names a new one.
`tag.updated`	A tag is renamed.
`tag.deleted`	A tag is deleted, and with it removed from every product.

A category’s data is { id, name, slug, parent, position }; a tag’s is { id, name, slug }. Tagging or untagging a product is a product.updated.

Expenses

Event	Fires when
`expense.created`	An expense is logged — by hand, by the Bee, or by a recurring expense on its schedule.
`expense.updated`	An expense changes.
`expense.deleted`	An expense is deleted.

{
  "id": "…",
  "amount": 2500000,
  "tax_amount": 0,
  "currency": "NGN",
  "occurred_at": "2026-09-11",
  "description": "Diesel",
  "category": { "id": "…", "name": "Utilities" },
  "payee": "Total Energies",
  "paid_to": null,
  "order": null,
  "source": "MANUAL"
}

Invoices

Event	Fires when
`invoice.created`	A draft invoice is created.
`invoice.issued`	An invoice is numbered and billed — by hand, or automatically by a payment milestone.
`invoice.voided`	An issued invoice is voided.
`invoice.paid`	An issued invoice is settled in full.
`invoice.deleted`	A draft invoice is deleted. Issued invoices are never deleted.

{
  "id": "…",
  "number": "INV-0042",
  "kind": "ORDER_MILESTONE",
  "status": "ISSUED",
  "order": "…",
  "milestone_sequence": 1,
  "customer": { "name": "Amina Bello", "email": "[email protected]" },
  "currency": "NGN",
  "subtotal": 35000000,
  "tax_total": 0,
  "total": 24500000,
  "issued_at": "2026-09-11T10:00:00Z",
  "issue_trigger": "MILESTONE_STAGE",
  "void_reason": null
}

An invoice’s balance comes from its order’s payments, so invoice.paid fires for each issued invoice when the order becomes fully paid — alongside order.paid. Its data is { id, number, order, currency, total }.

Payment milestone templates

Event	Fires when
`milestone_template.created`	A template (such as “70/30 split”) is created.
`milestone_template.updated`	A template’s name or splits change.
`milestone_template.deleted`	A template is deleted.

data carries id, name, splits (each { "label": "Deposit", "pct": 70 }) and is_default.

Stock

Event	Fires when
`stock_count.opened`	A stock count starts. `data`: `{ id, pool, line_count }`.
`stock_count.closed`	A stock count closes and its adjustments are applied to stock.
`stock_count.abandoned`	A stock count is abandoned without changing stock.
`stock_transfer.created`	Stock moves between pools.
`stock_pool.adjusted`	Someone sets a pool’s on-hand figure for a variant by hand.

Counting a line changes no stock, so it fires nothing; stock_count.closed carries what the count changed:

{
  "id": "…",
  "currency": "NGN",
  "adjustment_count": 2,
  "totals": {
    "line_count": 14,
    "counted_count": 14,
    "variance_count": 2,
    "shortfall_value_base": 900000,
    "surplus_value_base": 0,
    "explained_value_base": 900000,
    "unaccounted_value_base": 0
  }
}

A stock_pool.adjusted event:

{
  "pool": "PRODUCTION",
  "pool_id": "…",
  "variant_id": "…",
  "product_id": "…",
  "label": "Adire Kaftan / M",
  "delta": 3,
  "on_hand": 5,
  "reserved": 0,
  "adjusted_by": "Tolu"
}

A transfer’s data is { id, from_pool, to_pool, lines, note, moved_at }, where each pool is { id, code } and each line { variant_id, sku, label, qty }.

Bee tasks

Event	Fires when
`task.created`	The Bee opens a task, or someone creates one by hand.
`task.updated`	A task’s status or assignee changes, or its proposed fix is accepted or declined. Progress counts moving is not an event.

data carries the task’s id, source, type, category, status, title, value_line, count_total, count_remaining, amount_minor, currency, proposal_status, assignee, snoozed_until, resolved_by and resolved_at.

Imports

Event	Fires when
`import.completed`	A bulk CSV import finishes successfully.
`import.failed`	A bulk CSV import fails.

Get Started

Core Concepts

Guides

Set one up

What a delivery looks like

Check the signature

Reply quickly, and we’ll retry

Test it

Products

Collections

Bundles

Orders

Fulfillments

Customers

Materials and supplies

Suppliers

Product categories and tags

Expenses

Invoices

Payment milestone templates

Stock

Bee tasks

Imports

​Set one up

​What a delivery looks like

​Check the signature

​Reply quickly, and we’ll retry

​Test it

​Events you can subscribe to

​Products

​Collections

​Bundles

​Orders

​Fulfillments

​Customers

​Materials and supplies

​Suppliers

​Product categories and tags

​Expenses

​Invoices

​Payment milestone templates

​Stock

​Bee tasks

​Imports

Set one up

What a delivery looks like

Check the signature

Reply quickly, and we’ll retry

Test it

Events you can subscribe to

Products

Collections

Bundles

Orders

Fulfillments

Customers

Materials and supplies

Suppliers

Product categories and tags

Expenses

Invoices

Payment milestone templates

Stock

Bee tasks

Imports