Webhooks

A webhook is a POST request that BIRP sends to a URL of yours when data of the company changes. Your system learns about a new order or a changed stock level without asking the API again and again.

What BIRP sends

Each request carries one event as a JSON body: its id, its type, when the change happened, the version of the contract, and the record the event is about.

{
  "api_version": "v1",
  "data": {
    "archived_at": null,
    "barcode": "2000000000015",
    "category_id": "00000000-0000-4000-8000-000000000021",
    "created_at": "2026-09-01T07:30:00.000Z",
    "currency": "MDL",
    "external_ids": [
      {
        "external_id": "1042",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000011",
    "image_url": null,
    "kind": "goods",
    "name": "Wheat flour 25 kg",
    "price": "12.50",
    "sku": "SP-FLOUR-25",
    "status": "active",
    "unit": "kg",
    "updated_at": "2026-09-28T14:05:12.417Z"
  },
  "id": "00000000-0000-4000-8000-000000000101",
  "occurred_at": "2026-09-28T14:05:12.417Z",
  "type": "product.updated"
}

The data is the state when the event is sent

data is the record as the API returns it when BIRP sends the event, not a copy taken at the time of the change. Updates of a record made within a few seconds arrive as one event, with the final state.

A category, a customer, an order or an invoice deleted in BIRP comes as its id and "status": "deleted". A product removed from BIRP for good comes as archived.

At least once, in no fixed order

• An event can arrive more than once. After a timeout, for example, BIRP tries again even if your system received the first attempt.

• Events can arrive out of order. Before you overwrite a record, compare updated_at: skip the event only when the one you hold is later. A stock level has none, so read it from the API when the order matters.

• An event about a record deleted before the event went out is not sent. Its deletion event is, so you can receive a deletion for a record you never heard of.

• Handle each event once shows how.

Headers

Steps

1. Add a webhook endpoint in BIRP and choose its events. See Register a webhook endpoint.

2. Check the signature of every request. See Verify webhook signatures.

3. Store the event and answer with a 2xx status within 10 seconds; do the work after. See Retries and pauses.

Related

• register-webhook-endpoint
• verify-webhook-signatures
• webhook-events
• handle-webhooks-once