Webhook endpoints

Create a webhook endpoint

POST/v1/webhooks

Registers an endpoint that will receive signed event deliveries. The signing secret is returned ONCE in this response and can never be read again (rotate to get a new one). The payload shape is pinned to the Fansquare-Version of this request. Deliveries are signed with HMAC-SHA256 over {timestamp}.{body} (headers Fansquare-Signature / Fansquare-Signature-Timestamp); reject stale timestamps (>5 min). Webhooks are an accelerator, not a source of truth: after an outage or a disabled period, reconcile through the pull API (GET /v1/orders, …).

Required scopewrite:webhooks

Rate limit60 requests per minute

curl -X POST 'https://api.fansquare.so/v1/webhooks' \
  -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"
  ]
}'

{
  "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",
  "secret": "fsq_whsec_pBZQSjuC8yWOLOpRucfKjAkCRfDiZtNu"
}

Parameters

Headers

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

Body

application/json

urlstringrequired
Destination URL. https only; localhost and private ranges are rejected.
format urimax length 2000
labelstringrequired
Name of the endpoint, for your own reference.
min length 1max length 100
enabled_event_typesarray of stringsrequired
Event types to deliver to this endpoint. ping needs no subscription: it is sent by POST /v1/webhooks/{endpoint_id}/ping.
Valuesorder.createdorder.refundedassignment.updatedconversation.ai_control_requestedmin items 1max items 4
allowed_creator_idsarray of strings
Restrict deliveries to these creators (Fansquare ids). Empty = all, including future ones; with a key restricted to some creators, empty = the creators of the key, and a creator outside its scope returns unknown_creator.
Default []max items 50

Response

Created, 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
secretstringrequired
Signing secret, shown ONCE: store it now.

curl -X POST 'https://api.fansquare.so/v1/webhooks' \
  -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"
  ]
}'

{
  "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",
  "secret": "fsq_whsec_pBZQSjuC8yWOLOpRucfKjAkCRfDiZtNu"
}