DevelopersGet API Key

Enterprise: the API, webhooks and MCP server are live for schools on the Enterprise plan. The owner allows every key and AI connection. Ask about Enterprise

On this page

API Reference / App Webhooks

App Webhooks

Dedicated private connectors manage their own callback subscriptions. These routes use an app key, not an ordinary API key or OAuth agent token. Event-area permissions and current locations determine what can be delivered.

3,000requests per UTC hour
10requests a second, in bursts
429when over, with Retry-After and X-RateLimit-Remaining

Per key or agent connection, on the Enterprise plan.

POST/v1/webhook_endpoints

Create an app webhook subscription

For dedicated app:zapier, app:make or app:n8n keys only. A general API key or agent token cannot call this management route. Each selected event needs read or write access to its own area, and locations cannot exceed the app key. The route’s families grouping does not replace these event-specific checks.

Access: Dedicated app key with the matching event-area permissions and locations.

Headers

  • AuthorizationstringRequired

    Bearer <token>: an API key or an agent OAuth access token. App subscription routes require a dedicated app key.

  • Swum-Versiondate

    Pins the response shape. Default: 2026-10-25.

  • Idempotency-KeystringRequired

    Any unique string, like a UUID. Send the same key again and you get the first answer back instead of doing it twice. Keys last 24 hours.

Body

  • urluriRequired

    At most 2048 characters.

  • eventsstring[]Required
  • location_idsstring[]

    At most 100 items.

App-owned lifecycle

Subscriptions are bound to the exact app key. Store the returned signing secret in protected connector state and verify raw bytes before processing an event. Callback URLs must be public HTTPS on port 443, with no redirects. Matching subscriptions are reused; reconnect resets the disabled failure interval. This management call does not create a Swummy proposal.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/webhook_endpoints" \
  -X POST \
  -H "Authorization: Bearer ${SWUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
  --data '{"url":"https://hooks.example.test/swum","events":["family.created"],"location_ids":["pool_example"]}'
200Subscription and signing secretapplication/json
{
  "endpoint": {
    "id": "we_app_example",
    "url": "https://hooks.example.test/swum",
    "description": "Swum connector",
    "events": [
      "family.created"
    ],
    "locationIds": [
      "pool_example"
    ],
    "source": "app:zapier",
    "apiKeyId": "app_key_example",
    "signed": true,
    "status": "healthy",
    "lastDeliveryAt": null,
    "lastStatusCode": null,
    "lastDeliveryFailed": false
  },
  "secret": "whsec_replace_with_returned_secret"
}
GET/v1/webhook_endpoints/{id}

Get an app subscription

Returns a subscription owned by this same dedicated app key. Missing, disabled, deleted or foreign subscriptions return not_found. The ordinary response excludes the signing secret.

Access: Dedicated app key with the matching event-area permissions and locations.

Path parameters

  • idstringRequired

    The exact Swum document id.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/webhook_endpoints/we_app_example" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"
200Subscriptionapplication/json
{
  "endpoint": {
    "id": "we_app_example",
    "url": "https://hooks.example.test/swum",
    "description": "Swum connector",
    "events": [
      "family.created"
    ],
    "locationIds": [
      "pool_example"
    ],
    "source": "app:zapier",
    "apiKeyId": "app_key_example",
    "signed": true,
    "status": "healthy",
    "lastDeliveryAt": null,
    "lastStatusCode": null,
    "lastDeliveryFailed": false
  }
}
GET/v1/webhook_endpoints/{id}/events/{eventId}

Get a canonical app event

Retrieves a retained canonical event for this app-owned subscription. Rechecks current key access, event selection, location, payload digest and retention; Attributed Links events and events not delivered to this endpoint are refused.

Access: Dedicated app key with the matching event-area permissions and locations.

Path parameters

  • idstringRequired

    The exact Swum document id.

  • eventIdstringRequired

    The exact Swum document id.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/webhook_endpoints/we_app_example/events/event_example" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"
200Canonical eventapplication/json
{
  "id": "event_example",
  "type": "family.created",
  "created": "2026-10-26T12:00:00.000Z",
  "owner_id": "owner_example",
  "data": {
    "family_id": "family_example",
    "swimmer_id": "",
    "class_id": "",
    "request_id": "",
    "status": "",
    "location_id": "pool_example"
  }
}
DELETE/v1/webhook_endpoints/{id}

Delete an app subscription

Disables only the subscription owned by this dedicated app key. It does not delete families, swimmers, payments or school data. Idempotency-Key is required.

Access: Dedicated app key with the matching event-area permissions and locations.

Headers

  • Idempotency-KeystringRequired

    Any unique string, like a UUID. Send the same key again and you get the first answer back instead of doing it twice. Keys last 24 hours.

Path parameters

  • idstringRequired

    The exact Swum document id.

Dedicated app key required

This route is available to the matching Zapier, Make or n8n app key, with normal request idempotency. It has no MCP tool and no Swummy proposal.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/webhook_endpoints/we_app_example" \
  -X DELETE \
  -H "Authorization: Bearer ${SWUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
  --data '{}'
200Subscription disabledapplication/json
{
  "ok": true
}