Webhook Endpoints
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) orcontent. See Payload modes.
- Name
version- Type
- integer
- Description
The payload version,
1.
- Name
status- Type
- string
- Description
active,pausedordisabled.
- Name
disabled_reason- Type
- string | null
- Description
Why the endpoint was disabled:
gone(it answered410 Gone) orfailing(no successful delivery for 5 days).nullotherwise.
- Name
failing_since- Type
- datetime | null
- Description
Start of the current failure streak: the first failed attempt after the last successful one.
nullwhen 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) andsucceeded(attempts answered with2xx).
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
idof the endpoint anddeleted,trueonce the endpoint has been deleted.
- Name
status- Type
- string
- Description
pending(waiting for its first attempt or a retry),succeededordead(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
nullwhen there was no response.
- Name
last_error- Type
- string | null
- Description
Error of the last attempt, for example
timeout,connect,tls,redirectorblocked_address, or why the delivery stopped:endpoint_gone,endpoint_disabled,endpoint_paused.nullwhen 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
statusispending.
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
localhostor a host name ending in.localhost,.internalor.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:
| Action | Allows |
|---|---|
read | Listing endpoints, their deliveries, the event log, attempts and the event-type catalogue |
create | Creating endpoints |
update | Editing, pausing and resuming endpoints, revealing and rotating the signing secret, sending test events, recovering and redelivering |
delete | Deleting 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:
| Limit | Value |
|---|---|
| Endpoints per environment | 20 |
| Collections in one endpoint's filter | 50 |
| Request timeout | 10 seconds |
| Body size with content | 256 KB; a larger event is sent as references with "truncated": true |
| Deliveries in flight per endpoint | 10 |
| Deliveries per second per endpoint | 50; more wait in the queue |
| Event history | 30 days |
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
referencesorcontent.
- Name
version- Type
- integer
- Default
- default:1
- Description
Payload version.
1is the only version.
Errors
- Name
400 Bad Request- Description
required-urlorevent_typesis missinginvalid_url- the URL is not allowed;detail.reasonistoo_long,scheme,userinfo,portorhostunknown_event_type-detail.unknownlists the unknown typesunknown_collection-detail.unknownlists collection keys that do not exist in the environmenttoo_many_collections- more than 50 collection keysunsupported_version-detail.supportedlists the supported versionsunknown_field-detail.unknownlists fields the endpoint does not acceptinvalid_field- a field has the wrong type or value;detail.fieldnames itinvalid_body- the body is not a JSON object
- Name
403 Forbidden- Description
forbidden- missingwebhooks:create, or the read access acontentendpoint needs
- Name
409 Conflict- Description
limit_exceeded- the environment already has 20 endpoints
Request
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="
}
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,pausedordisabled.
- 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
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 }
}
]
}
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
curl https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
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 changeinvalid_field-statusis notactiveorpaused
- Name
403 Forbidden- Description
forbidden- missingwebhooks:update, or the read access acontentendpoint needs
- Name
404 Not Found- Description
webhook_endpoint_not_found
Request
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"}'
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
curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
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
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 }
}
]
}
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- missingwebhooks:update
- Name
404 Not Found- Description
webhook_endpoint_not_found
Request
curl https://api.foxnose.net/v1/7c9h4pwu/webhooks/endpoints/3f6c2a8e-91d4-4b7a-a5e2-0c9d8b7f1e23/secret/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8Gx5FN2xCTE="
}
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.
nullwhen there is none left.
Request
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"
}
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_typeis missingunknown_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
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"
}
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
truewhen more failed deliveries remain.
Errors
- Name
400 Bad Request- Description
required-sinceis missinginvalid_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 firstendpoint_not_subscribed- every failed delivery found is for an event the endpoint's current event types or collection filter do not cover
Request
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
}