Webhooks

Public API webhooks let an integration receive outbound FITsociety events at a public HTTPS endpoint. These endpoints are management resources and use the same OAuth Bearer authentication, scopes, idempotency, response envelope, and rate-limit metadata as other Public API resources.

/public/v1/webhooks, /public/v1/webhooks/{id}, and /public/v1/webhooks/deliveries manage outbound webhook subscriptions. Provider receiver routes below /public/v1/webhooks/*, such as payment provider callbacks or InBody sync triggers, are separate inbound callback routes and keep provider-specific authentication.

Scopes

Scope	Purpose
`webhooks:read`	List and read outbound webhook subscriptions.
`webhooks:write`	Create, update, delete, and test outbound webhook subscriptions.
`webhook_deliveries:read`	List and inspect outbound webhook delivery attempts.

Events

Webhook subscriptions validate event names against the backend event registry. Unknown names are rejected on create and update.

System

Event	When it is sent
`subscription.test`	A test event requested through `POST /public/v1/webhooks/{id}/test`.

Members

Event	When it is sent
`client.created`	A client was created or linked to the company.
`client.updated`	Public-safe client profile metadata changed.
`client.archived`	A company-client relationship was archived.
`client.invited`	A client portal invite was sent.
`client.portal_access.changed`	A client’s portal access status changed.
`client.relationship.approved`	A client relationship request was approved.
`client.relationship.rejected`	A client relationship request was rejected.
`client.note.created`	A client note was created. Note title/body are not included.
`client.note.updated`	A client note was updated. Note title/body are not included.
`client.note.deleted`	A client note was deleted.

Bookings and calendar

Event	When it is sent
`booking.created`	A booking was created.
`booking.updated`	Attendance, timing, or safe booking metadata changed.
`booking.cancelled`	A booking was cancelled after policy handling.
`booking_request.created`	A booking entered the coach approval flow.
`booking_request.approved`	A booking request was approved.
`booking_request.rejected`	A booking request was rejected.
`recurring_booking.changed`	A recurring booking was updated or cancelled.
`calendar_task.created`	A calendar task was created.
`calendar_task.updated`	A calendar task was updated.
`calendar_task.cancelled`	A calendar task was cancelled.

Finance

Event	When it is sent
`invoice.created`	An invoice was created.
`invoice.sent`	An invoice copy was sent.
`invoice.overdue`	A past-due invoice received a payment reminder.
`invoice.cancelled`	Reserved for a native invoice cancellation transition.
`invoice.paid`	An invoice moved to paid state.
`payment.succeeded`	A payment moved to a successful final state.
`payment.failed`	A payment moved to a failed final state.
`payment.request.created`	A payment request was created.
`payment.request.cancelled`	A payment request was cancelled.
`chargeback.created`	A new chargeback was recorded.
`subscription.changed`	A membership/subscription was materially changed.
`subscription.cancelled`	A membership/subscription was cancelled.

Products and credits

Event	When it is sent
`client_product.assigned`	A product was assigned to a client.
`client_product.revoked`	A client product was revoked or cancelled.
`credit.assigned`	Credits were assigned to a client.
`credit.adjusted`	A client credit balance was adjusted.
`credit.revoked`	Credits were revoked or expired.
`membership.assigned`	A membership was assigned to a client.

Forms

Event	When it is sent
`form.assigned`	A form was assigned to a client.
`form.submitted`	A form was submitted. Answers and media are not included.
`intake.submitted`	An intake form was submitted. Answers and media are not included.
`checkup.assigned`	A check-up form was assigned to a client.
`checkup.submitted`	A check-up form was submitted. Answers and media are not included.

Progress

Event	When it is sent
`measurement.created`	A measurement entry was created. The measurement value is not included.
`measurement.updated`	A measurement entry was updated. The measurement value is not included.
`progress_photo.created`	A progress photo was added. Image URLs are not included.
`goal.updated`	A client goal was updated.
`habit_entry.created`	A habit entry was created. Notes and values are not included.

Documents

Event	When it is sent
`document.linked`	Document metadata was linked to a client. URLs are not included.
`document.updated`	Document metadata was updated.
`document.archived`	A document metadata record was archived.

Payload contract

Every outbound delivery body has the same top-level shape:

Field	Type	Description
`id`	`string`	Stable webhook event id.
`type`	`string`	Event type, for example `client.created`.
`occurredAt`	`string`	UTC ISO-8601 timestamp when FITsociety recorded the event.
`data`	`object`	Event-specific public-safe payload.

data is intentionally compact. It includes ids, statuses, timestamps, and changed field names where relevant. It does not include raw model documents. When an integration needs full detail, call the relevant scoped Public API read endpoint with the ids from data.

Webhook payloads do not include secrets, access tokens, API keys, raw provider responses, request headers, payment provider ids, PDF/download URLs, image or media URLs, invoice line items, note bodies, form answers, health notes, free text rejection/reason messages, or internal audit/history arrays.

Endpoints

Method and path	Scope	Purpose
`GET /public/v1/webhooks`	`webhooks:read`	List webhook subscriptions.
`POST /public/v1/webhooks`	`webhooks:write`	Create a webhook subscription.
`GET /public/v1/webhooks/{id}`	`webhooks:read`	Get one webhook subscription.
`PATCH /public/v1/webhooks/{id}`	`webhooks:write`	Update a subscription name, status, URL, or event list.
`DELETE /public/v1/webhooks/{id}`	`webhooks:write`	Soft-delete a subscription.
`POST /public/v1/webhooks/{id}/test`	`webhooks:write`	Queue a `subscription.test` delivery.
`GET /public/v1/webhooks/deliveries`	`webhook_deliveries:read`	List delivery attempts.
`GET /public/v1/webhooks/deliveries/{id}`	`webhook_deliveries:read`	Get one delivery attempt.

Write requests require Idempotency-Key.

Target URL validation

Webhook targets must be public HTTPS URLs. The API rejects invalid URLs, non-HTTPS URLs, local-only hostnames, private IPv4 ranges, loopback addresses, link-local addresses, and private IPv6 addresses.

Request validation

Field	Used by	Required	Rule
`name`	create, update	create yes	Trimmed string, maximum 120 characters.
`url`	create, update	conditional	Public HTTPS URL. Required on create unless `target.url` is supplied.
`target.type`	create, update	no	Only `url` is supported.
`target.url`	create, update	conditional	Public HTTPS URL. Alternative to top-level `url`.
`targetType`	create	no	Legacy alias for target type. Only `url` is supported.
`events[]`	create, update	create yes	Non-empty array of supported event names from the registry. Unknown events are rejected.
`status`	update	no	`active` or `disabled`.
`id` path parameter	get, update, delete, test	yes	Webhook subscription ID belonging to the authenticated company and not deleted.
`subscriptionId` query parameter	list deliveries	no	Optional subscription filter. Invalid IDs return an empty delivery list.

The authenticated company is always derived from the Bearer token. Request payloads never accept companyId, createdByCoachId, secret hashes, retry counters, delivery timestamps, or signing-secret metadata.

Subscription response fields

List responses:

Field	Type	Nullable	Description
`data.page`	integer	no	Current page.
`data.limit`	integer	no	Page size after cap, maximum `100`.
`data.total`	integer	no	Total matching subscriptions.
`data.totalPages`	integer	no	Total pages.
`data.hasNextPage`	boolean	no	Next page availability.
`data.hasPrevPage`	boolean	no	Previous page availability.
`data.subscriptions[].id`	string	no	Webhook subscription ID.
`data.subscriptions[].name`	string	no	Subscription name.
`data.subscriptions[].status`	string	no	`active` or `disabled`. Deleted subscriptions are excluded from list responses.
`data.subscriptions[].events[]`	string[]	no	Subscribed event names.
`data.subscriptions[].target.type`	string	no	Target type, currently `url`.
`data.subscriptions[].target.url`	string	no	Public HTTPS target URL.
`data.subscriptions[].secret.prefix`	string	no	Signing-secret prefix metadata.
`data.subscriptions[].secret.last4`	string	no	Signing-secret last four characters.
`data.subscriptions[].secret.rotatedAt`	string	yes	Last secret rotation timestamp.
`data.subscriptions[].lastDeliveryAt`	string	yes	Last delivery attempt timestamp.
`data.subscriptions[].lastSuccessAt`	string	yes	Last successful delivery timestamp.
`data.subscriptions[].lastFailureAt`	string	yes	Last failed delivery timestamp.
`data.subscriptions[].createdAt`	string	yes	Creation timestamp.
`data.subscriptions[].updatedAt`	string	yes	Last update timestamp.

Single subscription responses from create, get, update, and delete:

Field	Type	Nullable	Description
`data.subscription.id`	string	no	Webhook subscription ID.
`data.subscription.name`	string	no	Subscription name.
`data.subscription.status`	string	no	`active`, `disabled`, or `deleted` after delete.
`data.subscription.events[]`	string[]	no	Subscribed event names.
`data.subscription.target.type`	string	no	Target type, currently `url`.
`data.subscription.target.url`	string	no	Public HTTPS target URL.
`data.subscription.secret.prefix`	string	no	Signing-secret prefix metadata.
`data.subscription.secret.last4`	string	no	Signing-secret last four characters.
`data.subscription.secret.rotatedAt`	string	yes	Last secret rotation timestamp.
`data.subscription.signingSecret`	string	no	One-time signing secret returned only by create responses.
`data.subscription.lastDeliveryAt`	string	yes	Last delivery attempt timestamp.
`data.subscription.lastSuccessAt`	string	yes	Last successful delivery timestamp.
`data.subscription.lastFailureAt`	string	yes	Last failed delivery timestamp.
`data.subscription.createdAt`	string	yes	Creation timestamp.
`data.subscription.updatedAt`	string	yes	Last update timestamp.

Create a webhook

curl -X POST \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: webhook-create-crm-sync-20260714" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "url": "https://example.com/fitsociety/webhooks",
    "events": ["client.created", "client.updated"]
  }' \
  https://api.fitsociety.io/public/v1/webhooks

The create response includes data.subscription.signingSecret exactly once. Store it securely. Later list and detail responses only return secret metadata: prefix, last4, and rotatedAt.

{
  "data": {
    "subscription": {
      "id": "66f7b8b1e13c8d25f4d3d90a",
      "name": "CRM sync",
      "status": "active",
      "events": ["client.created", "client.updated"],
      "target": {
        "type": "url",
        "url": "https://example.com/fitsociety/webhooks"
      },
      "secret": {
        "prefix": "whsec_12",
        "last4": "9abc",
        "rotatedAt": "2026-07-14T09:30:00.000Z"
      },
      "signingSecret": "whsec_0123456789abcdefghijklmnopqrstuvwxyz",
      "lastDeliveryAt": null,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "createdAt": "2026-07-14T09:30:00.000Z",
      "updatedAt": "2026-07-14T09:30:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_0123456789abcdef",
    "rateLimit": {
      "limit": 10,
      "remaining": 9,
      "resetSeconds": 1
    }
  }
}

Update, delete, and test responses

PATCH /public/v1/webhooks/{id} and DELETE /public/v1/webhooks/{id} return data.subscription.id, name, status, events[], target.type, target.url, secret.prefix, secret.last4, secret.rotatedAt, lastDeliveryAt, lastSuccessAt, lastFailureAt, createdAt, and updatedAt. Delete is a soft delete: it sets data.subscription.status = deleted and removes the subscription from future list/get responses. POST /public/v1/webhooks/{id}/test queues a subscription.test event only for an active subscription. Test response fields:

Field	Type	Nullable	Description
`data.test.eventId`	string	no	Created webhook event ID.
`data.test.deliveryIds[]`	string[]	no	Delivery IDs queued for dispatch.

Signing headers

FITsociety sends each outbound delivery as an HTTP POST with JSON body and these headers:

Header	Description
`X-FITsociety-Webhook-Event`	Event type, for example `client.created`.
`X-FITsociety-Webhook-Delivery`	Delivery id. Use this for idempotent receiver processing.
`X-FITsociety-Webhook-Timestamp`	Unix timestamp in seconds.
`X-FITsociety-Webhook-Signature`	`v1=<hex_hmac_sha256>` signature.

The signature uses the one-time signing secret and this signed string:

<timestamp>.<deliveryId>.<eventId>.<canonical_payload_json>

The payload JSON is canonicalized by sorting object keys recursively and keeping array order. Receivers should reject stale timestamps and compare the computed signature in constant time. Outbound payloads use this shape:

{
  "id": "66f7b8b1e13c8d25f4d3d92a",
  "type": "client.created",
  "occurredAt": "2026-07-14T09:31:00.000Z",
  "data": {
    "clientId": "66f7b8b1e13c8d25f4d3d93a"
  }
}

Deliveries and retries

A delivery is successful only when the target returns an HTTP 2xx response. FITsociety stores the response status, a redacted response body preview, and the last error summary for debugging.

Status	Meaning
`pending`	Delivery was created and has not been attempted yet.
`delivering`	Delivery attempt is in progress.
`delivered`	Target returned HTTP `2xx`.
`failed`	The last attempt failed and another retry may be scheduled.
`exhausted`	The delivery reached the maximum attempts.

Each delivery has maxAttempts: 3. Failed attempts are retried with exponential backoff, starting at 1 minute and then 2 minutes, with a 1 hour cap for future retry schedules. nextAttemptAt is null after success or exhaustion.

List deliveries

curl -X GET \
  -H "Authorization: Bearer <access_token>" \
  "https://api.fitsociety.io/public/v1/webhooks/deliveries?subscriptionId=66f7b8b1e13c8d25f4d3d90a"

Delivery list and detail responses use the Public API envelope and include meta.rateLimit when the request passed through the Public API rate limiter. Delivery list response fields:

Field	Type	Nullable	Description
`data.page`	integer	no	Current page.
`data.limit`	integer	no	Page size after cap, maximum `100`.
`data.total`	integer	no	Total matching deliveries.
`data.totalPages`	integer	no	Total pages.
`data.hasNextPage`	boolean	no	Next page availability.
`data.hasPrevPage`	boolean	no	Previous page availability.
`data.deliveries[].id`	string	no	Delivery ID.
`data.deliveries[].subscriptionId`	string	no	Webhook subscription ID.
`data.deliveries[].eventId`	string	no	Webhook event ID.
`data.deliveries[].eventType`	string	no	Event type.
`data.deliveries[].status`	string	no	`pending`, `delivering`, `delivered`, `failed`, or `exhausted`.
`data.deliveries[].attemptCount`	integer	no	Attempt count.
`data.deliveries[].maxAttempts`	integer	no	Maximum attempts.
`data.deliveries[].target.type`	string	no	Target type, currently `url`.
`data.deliveries[].target.url`	string	no	Public HTTPS target URL.
`data.deliveries[].responseStatusCode`	integer	yes	Last HTTP response status code.
`data.deliveries[].responseBodyPreview`	string	no	Redacted response body preview.
`data.deliveries[].errorMessage`	string	no	Redacted last error summary.
`data.deliveries[].nextAttemptAt`	string	yes	Next retry timestamp.
`data.deliveries[].deliveredAt`	string	yes	Delivered timestamp.
`data.deliveries[].lastAttemptAt`	string	yes	Last attempt timestamp.
`data.deliveries[].createdAt`	string	yes	Creation timestamp.
`data.deliveries[].updatedAt`	string	yes	Last update timestamp.

Delivery detail response fields:

Field	Type	Nullable	Description
`data.delivery.id`	string	no	Delivery ID.
`data.delivery.subscriptionId`	string	no	Webhook subscription ID.
`data.delivery.eventId`	string	no	Webhook event ID.
`data.delivery.eventType`	string	no	Event type.
`data.delivery.status`	string	no	`pending`, `delivering`, `delivered`, `failed`, or `exhausted`.
`data.delivery.attemptCount`	integer	no	Attempt count.
`data.delivery.maxAttempts`	integer	no	Maximum attempts.
`data.delivery.target.type`	string	no	Target type, currently `url`.
`data.delivery.target.url`	string	no	Public HTTPS target URL.
`data.delivery.responseStatusCode`	integer	yes	Last HTTP response status code.
`data.delivery.responseBodyPreview`	string	no	Redacted response body preview.
`data.delivery.errorMessage`	string	no	Redacted last error summary.
`data.delivery.nextAttemptAt`	string	yes	Next retry timestamp.
`data.delivery.deliveredAt`	string	yes	Delivered timestamp.
`data.delivery.lastAttemptAt`	string	yes	Last attempt timestamp.
`data.delivery.createdAt`	string	yes	Creation timestamp.
`data.delivery.updatedAt`	string	yes	Last update timestamp.

{
  "data": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false,
    "deliveries": [
      {
        "id": "66f7b8b1e13c8d25f4d3d91a",
        "subscriptionId": "66f7b8b1e13c8d25f4d3d90a",
        "eventId": "66f7b8b1e13c8d25f4d3d92a",
        "eventType": "client.created",
        "status": "delivered",
        "attemptCount": 1,
        "maxAttempts": 3,
        "target": {
          "type": "url",
          "url": "https://example.com/fitsociety/webhooks"
        },
        "responseStatusCode": 200,
        "responseBodyPreview": "{\"ok\":true}",
        "errorMessage": "",
        "nextAttemptAt": null,
        "deliveredAt": "2026-07-14T09:31:01.000Z",
        "lastAttemptAt": "2026-07-14T09:31:01.000Z",
        "createdAt": "2026-07-14T09:31:00.000Z",
        "updatedAt": "2026-07-14T09:31:01.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_0123456789abcdef",
    "rateLimit": {
      "limit": 10,
      "remaining": 8,
      "resetSeconds": 1
    }
  }
}

Start here

Public API guides

Access Devices

Scopes

Events

System

Members

Bookings and calendar

Finance

Products and credits

Forms

Progress

Documents

Payload contract

Endpoints

Target URL validation

Request validation

Subscription response fields

Create a webhook

Update, delete, and test responses

Signing headers

Deliveries and retries

List deliveries

​Scopes

​Events

​System

​Members

​Bookings and calendar

​Finance

​Products and credits

​Forms

​Progress

​Documents

​Payload contract

​Endpoints

​Target URL validation

​Request validation

​Subscription response fields

​Create a webhook

​Update, delete, and test responses

​Signing headers

​Deliveries and retries

​List deliveries

Scopes

Events

System

Members

Bookings and calendar

Finance

Products and credits

Forms

Progress

Documents

Payload contract

Endpoints

Target URL validation

Request validation

Subscription response fields

Create a webhook

Update, delete, and test responses

Signing headers

Deliveries and retries

List deliveries