Lifecycle hooks
A hook subscribes to an event and runs one of your operations when it fires. Each delivery is stored with its status, so a failed one can be found and replayed.
The events
Record events fire when a record is created, updated, deleted, published or unpublished. Other project events cover your users and their sessions, the outcome of an operation, finished imports, migrations and bulk changes, and the life of an organisation, from creation to a change in its members. A further set (team membership, plan, project and invitation changes) is subscribed on the workspace.
Declaring a hook
defineHook in config names an event and the key of the operation to run. A filter narrows the hook by equality on the event's top-level keys, typically to one model. A hook set up in the console can also target a built-in notification.
What a delivery carries
A delivery is an HTTP POST to the operation's endpoint. It is authenticated by a short-lived token in the X-Foir-Token header, which you verify against Fóir's JWKS, and there is no HMAC signature header. The body says what changed, by record id and model key, and carries no field content. The receiver reads the record back.
Tracking, retries and the dead-letter queue
Each delivery is a stored row with a status. foir hooks lists a hook's failed deliveries, replays one, and sends a synthetic delivery to test an endpoint. Retries and the circuit breaker belong to the operation the hook runs. A run that exhausts its retries lands in the dead-letter queue, where it can be inspected, retried or dismissed.
Ordering and loops
Delivery order is not guaranteed. Each delivery carries a sequence number, so a receiver can apply last-write-wins, and an execution id for dropping duplicates. A hook that triggers itself cannot run away: an operation already in the chain of causes is not run again, and a chain stops at three hops.
Read the detail
The lifecycle hooks guide covers the events, declaring a hook, and inspecting and replaying deliveries.