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.

  1. Open the environment and choose Webhooks in the navigation menu, then Add endpoint.
  2. Enter the Endpoint URL, an HTTPS address on the public internet (rules).
  3. Tick the Events to receive, and keep All collections in this environment or choose Only selected collections.
  4. Choose the Payload: References only or With content (see Payload modes).
  5. Click Create endpoint and store the Signing secret with your receiver.
  6. 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.

GroupEvent types
Resourcesresource.created, resource.updated (metadata such as the name), resource.deleted
Revisionsrevision.created, revision.updated (a draft edited in place), revision.published, revision.unpublished, revision.deleted
Collectionscollection.created, collection.updated, collection.schema_published, collection.deleted
Filesfile.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 both resource.created and revision.created.
  • Deleting a collection sends one collection.deleted, not one event per resource.
  • File events are sent once per status change. file.ready arrives when the file can be read through the Management API, and data.file.published says 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.number or file.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.

Was this page helpful?