Webhook endpoints

Update a webhook endpoint

PATCH/v1/webhooks/{endpoint_id}

Partial update. status: active re-enables an endpoint disabled manually or by the circuit breaker.

Required scopewrite:webhooks

Rate limit60 requests per minute

curl -X PATCH 'https://api.fansquare.so/v1/webhooks/67a55c69-e54b-4b90-a9f9-e000f12eb3fd' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/fansquare",
  "label": "Orders to accounting",
  "enabled_event_types": [
    "order.created"
  ],
  "allowed_creator_ids": [
    "m81IhLxdhzDGYs54rNp2"
  ],
  "status": "active"
}'

{
  "id": "67a55c69-e54b-4b90-a9f9-e000f12eb3fd",
  "url": "https://example.com/webhooks/fansquare",
  "label": "Orders to accounting",
  "secret_prefix": "fsq_whsec_pBZQSj",
  "enabled_event_types": [
    "order.created"
  ],
  "allowed_creator_ids": [
    "m81IhLxdhzDGYs54rNp2"
  ],
  "api_version": "2026-07-06",
  "status": "active",
  "disabled_reason": null,
  "disabled_at": null,
  "created_at": "2026-10-12T21:14:00.000Z"
}

Parameters

Headers

Fansquare-Versionstringrequired
API version to pin. Accepts the mineral name or the release date of a version.

Path

endpoint_idstringrequired
Webhook endpoint id (the id field of endpoint items).
format uuid

Body

application/json

urlstring
New destination URL. Same rules as at creation.
format urimax length 2000
labelstring
New name of the endpoint.
min length 1max length 100
enabled_event_typesarray of strings
Replaces the list of delivered event types.
Valuesorder.createdorder.refundedassignment.updatedconversation.ai_control_requestedmin items 1max items 4
allowed_creator_idsarray of strings
Replaces the creator scope (Fansquare ids). Empty = all, including future ones; with a key restricted to some creators, empty = the creators of the key.
max items 50
statusstring
Set active to re-enable a disabled endpoint (resets the breaker).
Valuesactivedisabled

Response

OK, application/json

idstringrequired
Webhook endpoint id. Path parameter of the /v1/webhooks/{endpoint_id} routes.
urlstringrequired
Destination URL (https only, public host).
labelstringrequired
Name of the endpoint, for your own reference.
secret_prefixstringrequired
First characters of the signing secret, for display. The full secret is only returned at creation/rotation.
enabled_event_typesarray of stringsrequired
Event types delivered to this endpoint.
Valuesorder.createdorder.refundedassignment.updatedconversation.ai_control_requested
allowed_creator_idsarray of stringsrequired
Creator scope. Empty = every creator of the agency, including future ones. A key restricted to some creators only sees the endpoints that cover nothing but its own creators.
api_versionstringrequired
API version (release date) pinned at creation. Payloads are rendered in this version forever.
statusstringrequired
disabled endpoints receive nothing until re-enabled.
Valuesactivedisabled
disabled_reasonstring | nullrequired
Why the endpoint is disabled: manual (paused through the API or the app), auto_breaker (disabled after 10 failed deliveries in a row). null while active.
Valuesmanualauto_breaker
disabled_atstring | nullrequired
When the endpoint was disabled (ISO 8601), null while active.
format date-time
created_atstringrequired
When the endpoint was created (ISO 8601).
format date-time

curl -X PATCH 'https://api.fansquare.so/v1/webhooks/67a55c69-e54b-4b90-a9f9-e000f12eb3fd' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/fansquare",
  "label": "Orders to accounting",
  "enabled_event_types": [
    "order.created"
  ],
  "allowed_creator_ids": [
    "m81IhLxdhzDGYs54rNp2"
  ],
  "status": "active"
}'

{
  "id": "67a55c69-e54b-4b90-a9f9-e000f12eb3fd",
  "url": "https://example.com/webhooks/fansquare",
  "label": "Orders to accounting",
  "secret_prefix": "fsq_whsec_pBZQSj",
  "enabled_event_types": [
    "order.created"
  ],
  "allowed_creator_ids": [
    "m81IhLxdhzDGYs54rNp2"
  ],
  "api_version": "2026-07-06",
  "status": "active",
  "disabled_reason": null,
  "disabled_at": null,
  "created_at": "2026-10-12T21:14:00.000Z"
}