Handle each event once

BIRP sends each event at least once, and in no fixed order. A few rules keep your system right when an event arrives twice or late.

Skip an event you already processed

id in the body, and the BIRP-Event-Id header, stay the same on every attempt of an event. Store the ids you processed for at least 7 days, and skip an event whose id you already hold.

Record the id in the same transaction as the change the event causes in your system. A crash between the two then cannot apply the change twice.

Apply changes in order

Events can arrive out of order, after a retry for example. Before you overwrite a record, compare updated_at: skip the event only when the one you hold is later, and apply it when they are equal, since a change of external ids keeps the same updated_at.

A stock level has no updated_at: when the order of two levels matters, read the level from the API. Events that mark a step, such as order.confirmed, apply as they come.

A deletion applies as it comes too, unless you already applied a later *.created of the same id: compare occurred_at. A category or an order can come back after a deletion event.

Deleted records

An event about a record deleted before the event went out is not sent; the deletion event of the record is. You can therefore receive a deletion for a record you never heard of: ignore it.

Read the record when you need it now

data is the record when BIRP sent the event. When you need the record as it is at this moment, read it from the API by its id, as Products and the other resource pages show.

Answer fast

Answer with a 2xx status as soon as the signature checks out and the event is stored. Then do the work, in a queue or a background job of your system.

Recover after an outage

The retries of a delivery last about a day. If your system was down for longer, read what changed with updated_since, as Pagination and filtering shows.

Stock levels have no updated_since: read them again in full. Records deleted in the meantime no longer appear in the lists, so compare the ids you hold with the ids you read.

Related

• webhooks-overview
• webhook-retries
• pagination-and-filtering
• idempotency