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.

HeaderValue
webhook-idThe event id, for example evt_01JCX3Q9W2B5V7RZ0D4K6M8P1T. Equal to id in the body
webhook-timestampThe time of this attempt, in Unix seconds
webhook-signatureOne or more signatures, separated by spaces, each in the form v1,<base64>
content-typeapplication/json
user-agentFoxNose-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/"
    }
  }
}
FieldDescription
idThe event id. The same across retries, redeliveries and endpoints. Use it to deduplicate
typeThe event type
versionThe payload version of the endpoint, 1
timestampWhen the change was made, in ISO 8601 UTC. Not the time of the delivery
testtrue for a test event
environmentThe environment key and its project key
dataThe objects the event is about (see below)
truncatedPresent 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

Eventsdata (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.updatedcollection {key, name}, links {collection}
collection.schema_publishedcollection {key, name}, schema {version, key}, links {collection}
collection.deletedcollection {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.usedupload_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:

EventsAdded in content mode
revision.created, revision.updated, revision.published, revision.unpublishedrevision.data: the revision's content, as the Management API returns it
collection.created, collection.updated, collection.schema_publishedThe 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:

  1. Read the raw request body as bytes, before any JSON parsing.
  2. Strip the whsec_ prefix and base64-decode the rest.
  3. Compute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body} and base64-encode it.
  4. Compare it in constant time with each v1, entry of webhook-signature. One match is enough.
  5. Reject the request if webhook-timestamp is 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:

AttemptDelay
1Immediately
25 seconds
315 seconds
430 seconds
51 minute
65 minutes
730 minutes
82 hours
95 hours
1010 hours
1110 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.

Was this page helpful?