Webhook Endpoints

Authentication: JWT | API Key

A webhook endpoint is a URL that receives a signed POST when a subscribed event happens in the environment. For event types, payloads, signature verification and retries, see Webhooks. The event log is documented in Webhook Events.

Every route requires the webhooks permission: read to list and read, create to create, update to change an endpoint and for every action on it (secret, test, recover), delete to delete.

Path Parameters

  • Name
    :env
    Type
    string
    Description

    Unique identifier of the environment.

  • Name
    :endpoint
    Type
    string
    Description

    The endpoint id (a UUID).


Endpoint Object

  • Name
    id
    Type
    string
    Description

    Unique identifier of the endpoint (a UUID).

  • Name
    url
    Type
    string
    Description

    The HTTPS URL deliveries are sent to. See Endpoint URLs for the rules it must meet.

  • Name
    description
    Type
    string
    Description

    A free-text description, at most 255 characters. Empty by default.

  • Name
    event_types
    Type
    array of strings
    Description

    The event types the endpoint receives. See Event types.

  • Name
    collection_keys
    Type
    array of strings
    Description

    Keys of the collections whose events the endpoint receives, at most 50. An empty list means every collection of the environment. Events that do not belong to a collection, such as a file that is not part of one, reach only endpoints with an empty list.

  • Name
    payload_mode
    Type
    string
    Description

    references (default) or content. See Payload modes.

  • Name
    version
    Type
    integer
    Description

    The payload version, 1.

  • Name
    status
    Type
    string
    Description

    active, paused or disabled.

  • Name
    disabled_reason
    Type
    string | null
    Description

    Why the endpoint was disabled: gone (it answered 410 Gone) or failing (no successful delivery for 5 days). null otherwise.

  • Name
    failing_since
    Type
    datetime | null
    Description

    Start of the current failure streak: the first failed attempt after the last successful one. null when the last attempt succeeded or there was none.

  • Name
    disabled_at
    Type
    datetime | null
    Description

    When the endpoint was disabled.

  • Name
    created_at
    Type
    datetime
    Description

    When the endpoint was created.

  • Name
    updated_at
    Type
    datetime
    Description

    When the endpoint was last changed.

  • Name
    stats_24h
    Type
    object
    Description

    Only in List Endpoints. Attempts of the last 24 hours: attempts (all attempts) and succeeded (attempts answered with 2xx).

Delivery Object

A delivery is one event sent to one endpoint, with all its attempts.

  • Name
    id
    Type
    string
    Description

    Unique identifier of the delivery (a UUID).

  • Name
    endpoint
    Type
    object
    Description

    id of the endpoint and deleted, true once the endpoint has been deleted.

  • Name
    status
    Type
    string
    Description

    pending (waiting for its first attempt or a retry), succeeded or dead (failed for good).

  • Name
    attempts
    Type
    integer
    Description

    Number of attempts made.

  • Name
    last_status_code
    Type
    integer | null
    Description

    HTTP status of the last attempt, or null when there was no response.

  • Name
    last_error
    Type
    string | null
    Description

    Error of the last attempt, for example timeout, connect, tls, redirect or blocked_address, or why the delivery stopped: endpoint_gone, endpoint_disabled, endpoint_paused. null when the endpoint answered with a status code and no other error.

  • Name
    created_at
    Type
    datetime
    Description

    When the delivery was created.

  • Name
    finished_at
    Type
    datetime | null
    Description

    When the delivery succeeded or failed for good.

  • Name
    next_attempt_at
    Type
    datetime | null
    Description

    When the next attempt is due. Set only while status is pending.


Endpoint URLs

An endpoint URL must:

  • use https://;
  • be at most 2,048 characters;
  • contain no user name or password;
  • use port 443 or a port from 1024 to 65535;
  • not name localhost or a host name ending in .localhost, .internal or .local;
  • not be an IP address in a refused range.

Refused addresses are the IPv4 ranges 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.0.0.0/24, 192.168.0.0/16, 198.18.0.0/15, 224.0.0.0/4 and 240.0.0.0/4; the IPv6 ranges ::/128, ::1/128, fc00::/7, fe80::/10, fec0::/10, 64:ff9b:1::/48, ff00::/8 and 100::/64; and IPv6 addresses that embed a refused IPv4 address (IPv4-mapped, IPv4-compatible, IPv4-translated, 6to4 and 64:ff9b::/96).

The host name is resolved before every attempt, not when the endpoint is saved. If it resolves to a refused address, the attempt fails with the error blocked_address.


Permissions

Webhooks use the webhooks permission type:

ActionAllows
readListing endpoints, their deliveries, the event log, attempts and the event-type catalogue
createCreating endpoints
updateEditing, pausing and resuming endpoints, revealing and rotating the signing secret, sending test events, recovering and redelivering
deleteDeleting endpoints

A content endpoint also needs resources:read, and collection-items:read on every collection in its filter, or on all collections when it has none. This is checked on create and when the URL, payload mode or filter changes. An endpoint is not tied to the user or key that created it.


Limits

The same on every plan:

LimitValue
Endpoints per environment20
Collections in one endpoint's filter50
Request timeout10 seconds
Body size with content256 KB; a larger event is sent as references with "truncated": true
Deliveries in flight per endpoint10
Deliveries per second per endpoint50; more wait in the queue
Event history30 days

POSTapi.foxnose.net/v1/:env/webhooks/endpoints/

Create Endpoint

Creates an endpoint. The response includes the signing secret; it can be read again later with Reveal Secret.

An environment can have at most 20 endpoints.

A content endpoint requires read access to the content it will deliver: resources:read, plus collection-items:read on every collection in collection_keys, or on all collections when collection_keys is empty.

Success Response: 201 Created

Request Body

  • Name
    url
    Type
    string
    Required
    required
    Description

    HTTPS URL to send deliveries to.

  • Name
    event_types
    Type
    array of strings
    Required
    required
    Description

    Event types to receive. At least one.

  • Name
    description
    Type
    string
    Description

    At most 255 characters.

  • Name
    collection_keys
    Type
    array of strings
    Default
    default:[]
    Description

    Collections to receive events from, at most 50. Empty for every collection.

  • Name
    payload_mode
    Type
    string
    Default
    default:references
    Description

    references or content.

  • Name
    version
    Type
    integer
    Default
    default:1
    Description

    Payload version. 1 is the only version.

Errors

  • Name
    400 Bad Request
    Description
    • required - url or event_types is missing
    • invalid_url - the URL is not allowed; detail.reason is too_long, scheme, userinfo, port or host
    • unknown_event_type - detail.unknown lists the unknown types
    • unknown_collection - detail.unknown lists collection keys that do not exist in the environment
    • too_many_collections - more than 50 collection keys
    • unsupported_version - detail.supported lists the supported versions
    • unknown_field - detail.unknown lists fields the endpoint does not accept
    • invalid_field - a field has the wrong type or value; detail.field names it
    • invalid_body - the body is not a JSON object
  • Name
    403 Forbidden
    Description
    • forbidden - missing webhooks:create, or the read access a content endpoint needs
  • Name
    409 Conflict
    Description
    • limit_exceeded - the environment already has 20 endpoints

Request

POST
/v1/:env/webhooks/endpoints/
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
  "url": "https://hooks.example.com/foxnose",
  "description": "Search index sync",
  "event_types": ["revision.published", "revision.unpublished", "resource.deleted"],
  "collection_keys": ["mK8nP3tYvBcX"],
  "payload_mode": "content"
}'

Response

{
  "id": "3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23",
  "url": "https://hooks.example.com/foxnose",
  "description": "Search index sync",
  "event_types": ["revision.published", "revision.unpublished", "resource.deleted"],
  "collection_keys": ["mK8nP3tYvBcX"],
  "payload_mode": "content",
  "version": 1,
  "status": "active",
  "disabled_reason": null,
  "failing_since": null,
  "disabled_at": null,
  "created_at": "2026-11-12T09:30:12.418226+00:00",
  "updated_at": "2026-11-12T09:30:12.418226+00:00",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8Gx5FN2xCTE="
}

GETapi.foxnose.net/v1/:env/webhooks/endpoints/

List Endpoints

Lists the environment's endpoints, newest first. Each item carries stats_24h. Never includes secrets.

Success Response: 200 OK

Query Parameters

  • Name
    status
    Type
    string
    Description

    Only endpoints with this status: active, paused or disabled.

  • Name
    limit
    Type
    integer
    Default
    default:100
    Description

    Items per page, at most 200.

  • Name
    offset
    Type
    integer
    Default
    default:0
    Description

    Items to skip. See Pagination.

Request

GET
/v1/:env/webhooks/endpoints/
curl https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23",
      "url": "https://hooks.example.com/foxnose",
      "description": "Search index sync",
      "event_types": ["revision.published", "revision.unpublished", "resource.deleted"],
      "collection_keys": ["mK8nP3tYvBcX"],
      "payload_mode": "content",
      "version": 1,
      "status": "active",
      "disabled_reason": null,
      "failing_since": null,
      "disabled_at": null,
      "created_at": "2026-11-12T09:30:12.418226+00:00",
      "updated_at": "2026-11-12T09:30:12.418226+00:00",
      "stats_24h": { "attempts": 42, "succeeded": 41 }
    }
  ]
}

GETapi.foxnose.net/v1/:env/webhooks/endpoints/:endpoint/

Retrieve Endpoint

Returns one endpoint. Never includes the secret or stats_24h.

Success Response: 200 OK

Errors

  • Name
    404 Not Found
    Description
    • webhook_endpoint_not_found - no endpoint with this id in the environment

Request

GET
/v1/:env/webhooks/endpoints/:endpoint/
curl https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

PATCHapi.foxnose.net/v1/:env/webhooks/endpoints/:endpoint/

Update Endpoint

Changes any of url, description, event_types, collection_keys, payload_mode, version and status. Send only the fields to change.

status accepts active or paused. Setting active on a paused or disabled endpoint resumes it and clears its failure streak. Events that happened while it was paused or disabled were not recorded for it and are not sent; deliveries that failed can be sent again with Recover.

When the change touches url, payload_mode or collection_keys and the endpoint uses content, the read access for content is checked again.

Success Response: 200 OK with the endpoint.

Errors

  • Name
    400 Bad Request
    Description

    The codes of Create Endpoint except required, for the fields sent, and:

    • empty_patch - the body has no field to change
    • invalid_field - status is not active or paused
  • Name
    403 Forbidden
    Description
    • forbidden - missing webhooks:update, or the read access a content endpoint needs
  • Name
    404 Not Found
    Description
    • webhook_endpoint_not_found

Request

PATCH
/v1/:env/webhooks/endpoints/:endpoint/
curl -X PATCH https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'

DELETEapi.foxnose.net/v1/:env/webhooks/endpoints/:endpoint/

Delete Endpoint

Deletes the endpoint and its pending deliveries. Its finished deliveries and attempts stay in the event log for 30 days, with endpoint.deleted: true.

Success Response: 204 No Content

Errors

  • Name
    404 Not Found
    Description
    • webhook_endpoint_not_found

Request

DELETE
/v1/:env/webhooks/endpoints/:endpoint/
curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

GETapi.foxnose.net/v1/:env/webhooks/endpoints/:endpoint/deliveries/

List Endpoint Deliveries

Lists the endpoint's deliveries, newest first. Each item is a delivery with the event it carries: event_id, and event with its id, type and test. event is null once the event has aged out of the history.

Success Response: 200 OK

Query Parameters

  • Name
    limit
    Type
    integer
    Default
    default:100
    Description

    Items per page, at most 200.

  • Name
    offset
    Type
    integer
    Default
    default:0
    Description

    Items to skip.

Errors

  • Name
    404 Not Found
    Description
    • webhook_endpoint_not_found

Request

GET
/v1/:env/webhooks/endpoints/:endpoint/deliveries/
curl https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/deliveries/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "9b1e7c42-5d3a-4f8e-b2c6-7a0d1e9f3c85",
      "endpoint": { "id": "3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23", "deleted": false },
      "status": "pending",
      "attempts": 2,
      "last_status_code": 503,
      "last_error": null,
      "created_at": "2026-11-12T09:41:07.530114+00:00",
      "finished_at": null,
      "next_attempt_at": "2026-11-12T09:41:28.902311+00:00",
      "event_id": "evt_01JCX3Q9W2B5V7RZ0D4K6M8P1T",
      "event": { "id": "evt_01JCX3Q9W2B5V7RZ0D4K6M8P1T", "type": "revision.published", "test": false }
    },
    {
      "id": "c4a8e2f1-7b6d-4e3c-9a1f-2d8b5c7e0a96",
      "endpoint": { "id": "3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23", "deleted": false },
      "status": "succeeded",
      "attempts": 1,
      "last_status_code": 204,
      "last_error": null,
      "created_at": "2026-11-12T09:35:44.201857+00:00",
      "finished_at": "2026-11-12T09:35:44.388420+00:00",
      "next_attempt_at": null,
      "event_id": "evt_01JCX3D8K4N6Q2W9T7Y5B3H1MZ",
      "event": { "id": "evt_01JCX3D8K4N6Q2W9T7Y5B3H1MZ", "type": "revision.published", "test": true }
    }
  ]
}

GETapi.foxnose.net/v1/:env/webhooks/endpoints/:endpoint/secret/

Reveal Secret

Returns the endpoint's current signing secret, the newest one when a rotation is in progress. Requires webhooks:update.

Success Response: 200 OK

Errors

  • Name
    403 Forbidden
    Description
    • forbidden - missing webhooks:update
  • Name
    404 Not Found
    Description
    • webhook_endpoint_not_found

Request

GET
/v1/:env/webhooks/endpoints/:endpoint/secret/
curl https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/secret/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8Gx5FN2xCTE="
}

POSTapi.foxnose.net/v1/:env/webhooks/endpoints/:endpoint/secret/rotate/

Rotate Secret

Creates a new signing secret and returns it. The previous secret stays valid for 24 hours, and deliveries carry a signature for each valid secret; with expire_previous_now it stops at once. Requires webhooks:update.

Success Response: 200 OK

Request Body

  • Name
    expire_previous_now
    Type
    boolean
    Default
    default:false
    Description

    Stop signing with the previous secret immediately.

Response

  • Name
    secret
    Type
    string
    Description

    The new secret.

  • Name
    previous_secret_expires_at
    Type
    datetime | null
    Description

    When the previous secret stops being used. null when there is none left.

Request

POST
/v1/:env/webhooks/endpoints/:endpoint/secret/rotate/
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/secret/rotate/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{}'

Response

{
  "secret": "whsec_Q2b7Fz1kR8nYc4Lm0VtX9pWs3dHj6GaEuKo5NiBrT1A=",
  "previous_secret_expires_at": "2026-11-13T10:02:51.774102+00:00"
}

POSTapi.foxnose.net/v1/:env/webhooks/endpoints/:endpoint/test/

Send Test Event

Sends a sample event of the given type to this endpoint only, with "test": true in the envelope. The sample has the shape of a real event of that type in the endpoint's payload mode, with placeholder values. It is sent whatever the endpoint's event types and collection filter. The endpoint must be active.

Success Response: 202 Accepted

Request Body

  • Name
    event_type
    Type
    string
    Required
    required
    Description

    Any type from the catalogue.

Errors

  • Name
    400 Bad Request
    Description
    • required - event_type is missing
    • unknown_event_type
  • Name
    404 Not Found
    Description
    • webhook_endpoint_not_found
  • Name
    409 Conflict
    Description
    • endpoint_not_active - the endpoint is paused or disabled

Request

POST
/v1/:env/webhooks/endpoints/:endpoint/test/
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/test/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{"event_type": "revision.published"}'

Response

{
  "event_id": "evt_01JCX4A2C6E8G0J3M5P7R9T1VX",
  "delivery_id": "e7d3b9a1-2c4f-4a8e-8b6d-5f1c0a9e7d24"
}

POSTapi.foxnose.net/v1/:env/webhooks/endpoints/:endpoint/recover/

Recover Failed Deliveries

Sends again the endpoint's failed (dead) deliveries created at or after since. Each one becomes a new pending delivery of the same event, due immediately.

Skipped: events that already have a pending or succeeded delivery to this endpoint, and events that the endpoint's current event types or collection filter do not cover. One call queues at most 10,000 deliveries; when more is true, call again with the same since.

Success Response: 202 Accepted

Request Body

  • Name
    since
    Type
    datetime
    Required
    required
    Description

    ISO 8601, within the last 30 days. A time without a zone is read as UTC.

Response

  • Name
    requeued
    Type
    integer
    Description

    Deliveries queued by this call.

  • Name
    more
    Type
    boolean
    Description

    true when more failed deliveries remain.

Errors

  • Name
    400 Bad Request
    Description
    • required - since is missing
    • invalid_since - not an ISO 8601 datetime, or older than 30 days
  • Name
    404 Not Found
    Description
    • webhook_endpoint_not_found
  • Name
    409 Conflict
    Description
    • endpoint_not_active - the endpoint is paused or disabled; resume it first
    • endpoint_not_subscribed - every failed delivery found is for an event the endpoint's current event types or collection filter do not cover

Request

POST
/v1/:env/webhooks/endpoints/:endpoint/recover/
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/recover/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{"since": "2026-11-10T00:00:00Z"}'

Response

{
  "requeued": 37,
  "more": false
}

Was this page helpful?