You are reading version v1.2, which is archived. See the current version
Webhooks
What BIRP sends to your webhook endpoints when data changes, and how to receive it.
Version v1.2, updated
On this page
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
Add a webhook endpoint in BIRP and choose its events. See Register a webhook endpoint.
Check the signature of every request. See Verify webhook signatures.
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