Webhooks
A webhook endpoint receives a signed HTTPS POST from FoxNose when something changes in an environment: a resource is created, a revision is published, a collection's schema changes, a file finishes processing. Webhooks are available on every plan and are not billed.
Deliveries follow Standard Webhooks, so any Standard Webhooks library can verify them. The exact format is in Webhook Payloads.
Setting Up an Endpoint
Endpoints belong to one environment and receive only its events.
- Open the environment and choose Webhooks in the navigation menu, then Add endpoint.
- Enter the Endpoint URL, an HTTPS address on the public internet (rules).
- Tick the Events to receive, and keep All collections in this environment or choose Only selected collections.
- Choose the Payload: References only or With content (see Payload modes).
- Click Create endpoint and store the Signing secret with your receiver.
- Click Send a test event to check that your receiver accepts deliveries.
The endpoint page shows recent deliveries and lets you edit, pause, resume, rotate the secret, send test events, recover failed deliveries and delete the endpoint. The Event log lists every event of the environment with its deliveries. The same operations are in the Webhooks API, under the webhooks permission type.
Event Types
An endpoint receives only the event types it subscribes to, for the collections in its filter. An event goes to the endpoints that are active and subscribed when it happens: an endpoint created later, or paused at that moment, does not receive it.
| Group | Event types |
|---|---|
| Resources | resource.created, resource.updated (metadata such as the name), resource.deleted |
| Revisions | revision.created, revision.updated (a draft edited in place), revision.published, revision.unpublished, revision.deleted |
| Collections | collection.created, collection.updated, collection.schema_published, collection.deleted |
| Files | file.ready, file.in_review, file.rejected, file.failed, upload_link.used |
- To follow content, subscribe to
revision.*. Every change of content is a revision event. Creating a resource, an upsert that creates one included, sends bothresource.createdandrevision.created. - Deleting a collection sends one
collection.deleted, not one event per resource. - File events are sent once per status change.
file.readyarrives when the file can be read through the Management API, anddata.file.publishedsays whether the Flux API serves it at that moment. A file outside a collection reaches only endpoints without a collection filter.
List Event Types returns every type with a JSON Schema of its data.
Payload Modes
- References only (the default): ids, status and Management API
links. Fetch the object when you need it. - With content: also a snapshot of the content at the moment of the change, such as a revision's data, a collection's schema or a file's agent-ready text.
Each event describes its own moment, so a late event tells you about the change it reports, not the current state. A delivery with content falls back to references, marked "truncated": true, when it would exceed 256 KB or the snapshot has expired after 31 hours. See Content mode.
Verifying Signatures
Every delivery is signed with HMAC-SHA256 using the endpoint's signing secret. Verify it before trusting the body, and answer with a 2xx within 10 seconds; do slow work after responding. A Standard Webhooks library does the whole check:
Verify a delivery
# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook
wh = Webhook("whsec_...")
event = wh.verify(request.get_data(), dict(request.headers)) # raises on failure
To verify without a library, see Verifying a signature.
Rotating the secret keeps the previous one valid for 24 hours, so receivers can switch without dropping deliveries. You can end the overlap at once.
Delivery and Retries
- At least once. The same event can arrive more than once; deduplicate on its
id, which stays the same across retries and endpoints. - Retries. A failed attempt is retried 10 times over about 28 hours, starting after 5 seconds. See the retry schedule.
- No ordering. Deliveries can arrive out of order. Order by
timestamp,revision.numberorfile.generation.
Failing Endpoints
If deliveries keep failing, the organization's owner and admins are emailed after 24 hours and after 4 days. After 5 days without a success the endpoint is disabled, and an endpoint that answers 410 Gone is disabled at once. A disabled endpoint receives no new events: fix the receiver, resume the endpoint, then recover what failed.
Recovering and Redelivering
- Recover failed deliveries sends again every failed delivery of an endpoint since a time you choose, within 30 days.
- Redeliver sends one event from the event log again, with the same
id. - Pause stops new events for an endpoint; events that happen while it is paused are not recorded for it.
- Send test event delivers a sample of any type, marked
"test": true, to one endpoint.
History
Events, deliveries and attempts stay in the event log for 30 days, with the status code, latency, error and the first 1 KB of the response of each attempt. The log shows events in their references form; content snapshots are sent to endpoints only. Limits on endpoints and throughput are in the Webhooks API reference.