Laboratory › Developers › Webhooks
Webhooks
A delivery service needs retries, a dead-letter path, signature rotation, replay protection and delivery logs — real operational burden — to serve zero subscribers polling a feed that changes rarely. The changes endpoint and the Atom feed cover the need.
The contract it will honour
Written down now, while nothing depends on it, so it cannot be invented differently later under pressure to ship.
- Event types: claim.published, claim.superseded, claim.withdrawn, claim.replication_added, claim.falsifier_executed, evidence.updated, dataset.released, module.released, status.incident, key.revoked.
- Each delivery carries an event id, a timestamp and a signature over the raw body; consumers verify before parsing.
- Replay protection through the event id and timestamp; deliveries are idempotent by event id.
- Retries with backoff, a visible delivery log and a test delivery that is unmistakably a test.
- A webhook is a notification. The authoritative state is always the version URL it points at.
Event types
| Event | Fires when |
|---|---|
claim.published | A new claim identity or a new version becomes public. |
claim.superseded | A version is replaced. The prior version stays published. |
claim.withdrawn | A claim identity is retracted, with a reason. |
claim.falsifier_executed | A registered falsifier ran — whether it survived or failed. |
claim.replication_added | A reproduction or independent replication object is attached. |
evidence.updated | An evidence object attached to a published claim changes. |
dataset.released · module.released | A dataset or module clears release review. |
status.incident | An operational incident opens or closes. Never a scientific event. |
key.revoked | A credential is revoked. Requires credentials to exist first. |
Note that weakening events are first-class. A feed that only ever announces new publications is not reporting on a laboratory.
A webhook is a notification, never the record
A delivery tells you something happened. The authoritative state is always the version URL it points at, fetched fresh. A consumer that acts on payload contents without re-reading the record will eventually act on a replayed, reordered or forged delivery — which is why signature verification happens before parsing, not after.
PreviousSDKs
NextPlayground