Webhook Payloads
The format of a webhook delivery. What webhooks do and how to use them is in Webhooks.
Headers
Each delivery is an HTTPS POST with a JSON body.
| Header | Value |
|---|---|
webhook-id | The event id, for example evt_01JCX3Q9W2B5V7RZ0D4K6M8P1T. Equal to id in the body |
webhook-timestamp | The time of this attempt, in Unix seconds |
webhook-signature | One or more signatures, separated by spaces, each in the form v1,<base64> |
content-type | application/json |
user-agent | FoxNose-Webhooks/1 |
Envelope
revision.published, references only
{
"id": "evt_01JCX3Q9W2B5V7RZ0D4K6M8P1T",
"type": "revision.published",
"version": 1,
"timestamp": "2026-11-12T09:41:07.512Z",
"test": false,
"environment": { "key": "7c9h4pwu", "project": "p9x8y7z6" },
"data": {
"collection": { "key": "mK8nP3tYvBcX" },
"resource": { "key": "r5tGh2kLmN9q" },
"revision": {
"key": "rv8JkL2mNpQ4",
"number": 3,
"status": "published",
"schema_version": "v3Hn7KpQ2sTx",
"schema_version_number": 2,
"is_valid": true,
"created_at": "2026-11-12T09:40:58.104Z",
"published_at": "2026-11-12T09:41:07.498Z",
"unpublished_at": null
},
"previous_revision": { "key": "rv2HgF7dSaQ1", "number": 2 },
"links": {
"resource": "https://api.foxnose.net/v1/7c9h4pwu/collections/mK8nP3tYvBcX/resources/r5tGh2kLmN9q/",
"revision": "https://api.foxnose.net/v1/7c9h4pwu/collections/mK8nP3tYvBcX/resources/r5tGh2kLmN9q/revisions/rv8JkL2mNpQ4/"
}
}
}
| Field | Description |
|---|---|
id | The event id. The same across retries, redeliveries and endpoints. Use it to deduplicate |
type | The event type |
version | The payload version of the endpoint, 1 |
timestamp | When the change was made, in ISO 8601 UTC. Not the time of the delivery |
test | true for a test event |
environment | The environment key and its project key |
data | The objects the event is about (see below) |
truncated | Present and true when an event type that carries content is delivered to a With content endpoint without its content (see Payload modes) |
Objects inside data use the field names of the matching Management API objects. links holds Management API URLs that return the object with an API key. Ignore fields you do not know: fields can be added to an event without a new payload version.
Data by event type
| Events | data (references only) |
|---|---|
resource.* | collection {key}, resource {key, name, external_id}, links {resource} |
revision.* | collection {key}, resource {key}, revision {key, number, status, schema_version, schema_version_number, is_valid, created_at, published_at, unpublished_at}, links {resource, revision}. revision.published adds previous_revision {key, number}, the revision it replaces as the published one, when there is one |
collection.created, collection.updated | collection {key, name}, links {collection} |
collection.schema_published | collection {key, name}, schema {version, key}, links {collection} |
collection.deleted | collection {key} |
file.* | file {id, status, verdict, generation, kind, published}; collection {key} when the file belongs to a collection; resource {key} and links {file} when it belongs to a record |
upload_link.used | upload_link {id}, file {id}, collection {key}, links {upload_link}; links.file when the file belongs to a record |
The *.deleted events carry no links. The exact schema of every event type, in both payload modes, is returned by List Event Types.
Content mode
An endpoint with the content payload mode also receives a snapshot of the content at the moment of the change, merged into data:
| Events | Added in content mode |
|---|---|
revision.created, revision.updated, revision.published, revision.unpublished | revision.data: the revision's content, as the Management API returns it |
collection.created, collection.updated, collection.schema_published | The collection's settings in collection (description, alias, content_type, strict_reference, auto_remove_revisions, remove_drafts_on_publish, auto_remove_schema_versions, embedding_model, processing) and the collection's published schema in schema.json_schema when it has one |
file.* | File metadata in file (mime_type, size, page_count, source_format), verdict {verdict, reasons, public_reason}, untrusted: true, and, for file.ready, the agent-facing content in agent_content {original_filename, content, content_flags}. Other statuses carry agent_content: null with agent_content_unavailable: "not_ready" |
resource.*, revision.deleted, collection.deleted and upload_link.used are the same in both modes.
For the event types above, a content delivery carries references only, with "truncated": true, when the body would exceed 256 KB, the content snapshot has expired (after 31 hours) or was removed because its resource, revision, collection or environment was deleted or its file erased, or the event was recorded without one. Content is included only for event types and collections the endpoint subscribes to at the time of the delivery.
Verifying a signature
The signing secret is whsec_ followed by base64. To verify a delivery:
- Read the raw request body as bytes, before any JSON parsing.
- Strip the
whsec_prefix and base64-decode the rest. - Compute HMAC-SHA256 over
{webhook-id}.{webhook-timestamp}.{raw body}and base64-encode it. - Compare it in constant time with each
v1,entry ofwebhook-signature. One match is enough. - Reject the request if
webhook-timestampis more than 5 minutes from your clock.
Verify a delivery
import base64
import hashlib
import hmac
import json
import time
TOLERANCE_SECONDS = 5 * 60
def verify(secret: str, headers, body: bytes) -> dict:
"""headers: a case-insensitive mapping, such as Flask's or Django's request.headers.
body: the raw request body."""
msg_id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
signatures = headers["webhook-signature"]
if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
raise ValueError("timestamp outside the tolerance")
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
for entry in signatures.split(" "):
version, _, signature = entry.partition(",")
if version == "v1" and hmac.compare_digest(signature.encode(), expected):
return json.loads(body)
raise ValueError("no valid signature")
# Flask
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = "whsec_..." # from the endpoint page
@app.post("/foxnose/webhooks")
def foxnose_webhook():
try:
event = verify(SECRET, request.headers, request.get_data())
except (KeyError, ValueError):
abort(400)
# deduplicate on event["id"], then store or enqueue the event
return "", 204
During a secret rotation, each delivery carries two signatures, one per secret, for 24 hours.
Retry schedule
An attempt succeeds on a 2xx answer within 10 seconds. Redirects are never followed. A failed attempt is retried after these delays, measured from the previous attempt, each varying by up to 10% either way:
| Attempt | Delay |
|---|---|
| 1 | Immediately |
| 2 | 5 seconds |
| 3 | 15 seconds |
| 4 | 30 seconds |
| 5 | 1 minute |
| 6 | 5 minutes |
| 7 | 30 minutes |
| 8 | 2 hours |
| 9 | 5 hours |
| 10 | 10 hours |
| 11 | 10 hours |
After the 11th failed attempt, about 27.6 hours after the first, the delivery is dead. Each attempt carries a fresh webhook-timestamp, and its body is built at the time of the attempt.