Saves each shipment update once, even when the sender sends it again.
Send any delivery
Pick a delivery or edit it, then send it. The checks show where it stops.
POST /webhook HTTP/1.1
- Content-Type
- application/json
- X-Delivery-Timestamp
- 0
- X-Delivery-Signature
- ...
- sizenot reached
- timenot reached
- signaturenot reached
- formatnot reached
- storenot reached
Send a delivery to see the reply.
events 0 saved
| event_id | shipment | status | event_at |
|---|
shipments latest status
| shipment | status | latest_event_at | latest_event_id |
|---|
Nothing sent yet. Send a delivery.
Replies show up here.
Checked against the Python service: 1,500 random runs, 6,692 deliveries, 0 differences. In the browser, copies sent at once wait in line.
Recorded run of the Python service
A fresh database, five deliveries, then a restart and one more retry.
| Delivery | HTTP | Response body | Saved | Shipment |
|---|---|---|---|---|
| First deliveryevt_demo_001, in_transit | 200 | {"result": "recorded", "event_id": "evt_demo_001", "projection_changed": true} | 1 | in_transit |
| Same againsame ID, same body | 200 | {"result": "duplicate", "event_id": "evt_demo_001", "projection_changed": false} | 1 | in_transit |
| Changed bodysame ID, status delivered | 409 | {"error": "event_id_conflict"} | 1 | in_transit |
| Wrong signaturerefused before saving | 401 | {"error": "invalid_signature"} | 1 | in_transit |
| Older updateevt_demo_older, created | 200 | {"result": "recorded", "event_id": "evt_demo_older", "projection_changed": false} | 2 | in_transit |
| Restart, then retrysame database | 200 | {"result": "duplicate", "event_id": "evt_demo_001", "projection_changed": false} | 2 | in_transit |
How a duplicate is caught
The lookup and the save run in one transaction, so 24 copies at once give 1 saved and 23 duplicates.
event, event_at, digest = decode_event(body) with self.connect() as db: db.execute("BEGIN IMMEDIATE") previous = db.execute("SELECT digest FROM events WHERE event_id = ?", (event["event_id"],)).fetchone() if previous: if previous["digest"] != digest: raise ReceiptError(409, "event_id_conflict") return {"result": "duplicate", "event_id": event["event_id"], "projection_changed": False} db.execute("INSERT INTO events VALUES (?, ?, ?, ?, ?, ?)", (event["event_id"], digest, event["shipment"], event["status"], event_at, now)) current = db.execute("SELECT latest_event_at FROM shipments WHERE shipment = ?", (event["shipment"],)).fetchone() changed = current is None or event_at > current["latest_event_at"] if changed: db.execute("""INSERT INTO shipments VALUES (?, ?, ?, ?) ON CONFLICT(shipment) DO UPDATE SET status=excluded.status, latest_event_at=excluded.latest_event_at, latest_event_id=excluded.latest_event_id""", (event["shipment"], event["status"], event_at, event["event_id"])) return {"result": "recorded", "event_id": event["event_id"], "projection_changed": changed}
How two copies are compared
The keys are sorted and the spaces removed, then the text is hashed. Different spacing counts as the same update. A different value does not.
Older updates
An older update is saved too, but the shipment keeps the newest status.
python -m unittest test_receipts Ran 32 tests in 0.950s OK python server.py --db runs/study.sqlite --port 8962
Also tested
- old and future times
- unknown fields
- duplicate JSON keys
- invalid UTF-8
- deep nesting
- oversized bodies
- cross-origin requests
- unexpected hosts
Test page in the download
Limits
- One kind of event and one local SQLite database.
- A new signing key is made each time the service starts.
- The five-minute window and the ordering rule are choices for this study.
- It is not connected to a real courier, and it does not make other side effects run exactly once.
For a real project
First I reproduce the failure from one anonymized event. Then we agree the ID, retry and ordering rules before changing storage.