Skip to content

Webhook events

Every event type BIRP sends, when it is sent and what its data holds.

Version v1.2, updated

On this page

Each event has a type, such as order.confirmed, and is about one record. The table lists the types; each type has a page with an example of its body.

Event types

Type

Sent when

Data

product.created

A product was created in BIRP or through the API.

a product, with the fields of Products

product.updated

A field of the product that the API returns changed. Changes made within a few seconds of each other arrive as one event, with the final state.

a product, with the fields of Products

product.archived

The product was archived. When the product was removed from BIRP for good, data holds only its id and "status": "archived".

a product, with the fields of Products

product.restored

An archived product was made active again.

a product, with the fields of Products

category.created

A category was created in BIRP or through the API.

a category, with the fields of Categories

category.updated

A field of the category that the API returns changed. Changes made within a few seconds of each other arrive as one event, with the final state.

a category, with the fields of Categories

category.deleted

The category was deleted in BIRP, or its kind changed to one the API does not show. data holds its id and "status": "deleted"; if the category comes back, the same id arrives with category.created.

only the id of the record and "status": "deleted"

customer.created

A customer was created in BIRP or through the API.

a customer, with the fields of Customers

customer.updated

A field of the customer that the API returns changed. Changes made within a few seconds of each other arrive as one event, with the final state.

a customer, with the fields of Customers

customer.deleted

The customer was deleted in BIRP. data holds its id and "status": "deleted".

only the id of the record and "status": "deleted"

stock.level_changed

The quantity on hand of a product changed in a warehouse, for any reason. data is the stock level of that product, warehouse and unit; when nothing is left, quantity is "0". Changes made within a few seconds of each other arrive as one event, with the final state.

a stock level, with the fields of Warehouses and stock

order.created

A customer order was created in BIRP or through the API.

an order, with the fields of Orders

order.updated

A field of the order that the API returns changed, its lines included. Changes made within a few seconds of each other arrive as one event, with the final state.

an order, with the fields of Orders

order.confirmed

The order was confirmed.

an order, with the fields of Orders

order.cancelled

The order was cancelled.

an order, with the fields of Orders

order.status_changed

The status of the order changed to one other than confirmed or cancelled, which have their own events. previous_status holds the status before the change; when the status changed twice within a few seconds, the event goes from the first status to the last. data.status is the status when the event is sent.

an order, with the fields of Orders, and previous_status

order.deleted

The order was deleted in BIRP, or is no longer available through the API. data holds its id and "status": "deleted"; if the order comes back, the same id arrives with order.created.

only the id of the record and "status": "deleted"

invoice.created

An invoice was created in BIRP or through the API.

an invoice, with the fields of Invoices

invoice.updated

A field of the invoice that the API returns changed, its lines included. Changes made within a few seconds of each other arrive as one event, with the final state.

an invoice, with the fields of Invoices

invoice.issued

The invoice left draft for a status other than cancelled: it was issued, or it was created in or moved straight to a later status. It has its number, and the API accepts changes to its content only while it is a draft; status says where it stands.

an invoice, with the fields of Invoices

invoice.payment_recorded

A payment was recorded on the invoice. recorded_payment holds that payment; while it stays recorded, amount_paid and amount_due of the invoice include it. recorded_payment is null when the payment was removed before the event was sent.

an invoice, with the fields of Invoices, and recorded_payment

invoice.status_changed

The status of the invoice changed: from draft to issued only invoice.issued is sent, from draft to cancelled only this event, and from draft to any other status both. previous_status holds the status before the change, the first one when it changed twice within a few seconds. data.status is the status when the event is sent.

an invoice, with the fields of Invoices, and previous_status

invoice.deleted

The invoice was deleted in BIRP. data holds its id and "status": "deleted".

only the id of the record and "status": "deleted"

Merged changes

*.updated, *.status_changed and stock.level_changed merge the changes made within a few seconds into one event, with the final state.

An update made together with another event of the same record, such as order.confirmed, comes only as that event, since that event already carries the final state. To follow every change of a record, receive all the events of its resource.

Events that mark a step, such as order.created, order.confirmed or invoice.payment_recorded, are never merged: you receive each one.

Records deleted in BIRP

Categories, customers, orders and invoices deleted in BIRP send a *.deleted event with the id of the record and "status": "deleted". A product removed from BIRP for good sends product.archived with its id and "status": "archived".

The test event

webhook.test is sent only on request, from the page of a webhook endpoint in BIRP. It cannot be chosen in the list of events. See Register a webhook endpoint.

  • webhooks-overview
  • handle-webhooks-once
  • event-order-status-changed
  • event-stock-level-changed