Webhooks

This guide explains how to register a webhook and what your endpoint will receive
so you can be notified in real time when an account you have access to completes a
workout.

1. Overview

A webhook lets Myzone push an event to your server the moment it happens, instead of you
polling the API. You register a destination URL for an event; when the event occurs for
any account within your access, Myzone sends an HTTP POST to that URL.

Currently supported events:

2. Prerequisites

You must be on one of the following price tiers:

• Starter
• Growth
• Pro
• Partner

3. Authenticate

Obtain an access token from the Myzone Auth Portal using the OAuth 2.0
client-credentials grant.

4. Register a webhook

POST /v1/webhooks — requires write:webhooks and scope for associated data retrieval e.g. read:moves for the workout.completed event.

Specification

Register a webhook (Draft)

Request

curl -X POST https://ext-api.myzone.org/v1/webhooks \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "workout.completed",
    "url": "https://partner.example.com/hooks/myzone",
    "headers": { "x-api-key": "your-shared-secret" }
  }'

Response 201 Created

{
  "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "event": "workout.completed",
  "url": "https://partner.example.com/hooks/myzone",
  "status": "active"
}

• id is an opaque webhook identifier (a GUID). Store it — you need it to delete the
  webhook.
• status is active once delivery is live.

Idempotent: registering the same event + url again returns the existing webhook
rather than creating a duplicate (so you won't get double deliveries), and re-activates it
if it had been disabled.

5. List your webhooks

GET /v1/webhooks — requires read:webhooks.

Specification

List your webhooks (Draft)

Request

curl https://ext-api.myzone.org/v1/webhooks \
-H "Authorization: Bearer <access_token>

Response

[
  {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "event": "workout.completed",
    "url": "https://partner.example.com/hooks/myzone",
    "status": "active"
  }
]

6. Delete a webhook

DELETE /v1/webhooks/{id} — requires delete:webhooks. {id} is the id from create/list.

Specification

Delete a webhook (Draft)

Request

curl -X DELETE https://ext-api.myzone.org/v1/webhooks/3f2504e0-4f89-41d3-9a0c-0305e82c3301 \
  -H "Authorization: Bearer <access_token>"

Response

Returns 204 No Content. Deleting an id you don't own returns 404 Not Found.

7. What your endpoint receives

On each matching event, Myzone sends an HTTP POST to your url with a compact JSON
notification, plus any headers you configured. The body is a fixed, stable shape — a
lightweight notification, not the full event:

workout.completed event example:

{
  "type": "post_workout",
  "accountId": "a1b2c3d4-0000-0000-0000-abcdef123456",
  "moveId": "b7f9e2a1-1111-2222-3333-444455556666"
}

To fetch the full workout detail for the referenced move, call Retrieve a user's move
with your read:moves token, using both the accountId and moveId from the
notification above.

8. Handling deliveries — what your endpoint must do

• Respond quickly with a 2xx. Return 200 OK as soon as you've accepted the event and
  do your processing asynchronously. Slow responses delay delivery and may be treated as
  failures. The per-delivery timeout is ~10 seconds.
• Be idempotent. Delivery is at-least-once — the same event may arrive more than
  once (e.g. after a retry). De-duplicate on moveId.
• Authenticate the callback. Deliveries arrive over HTTPS. Use the headers secret you
  supplied at registration to verify the request really came from Myzone, and reject
  requests without it.
• Don't assume ordering. Events are independent; don't rely on receiving them in order.

Retries & auto-disable

• A failed delivery (non-2xx, timeout, or connection error) is retried with exponential
  backoff (roughly 1s → 2s → 4s).
• If your endpoint fails repeatedly over a sustained period, the webhook is automatically
  disabled to protect both sides. To resume, fix your endpoint and re-register the
  same event + url — that re-activates the existing subscription.

9. Access scope & changes

• A webhook is scoped to the facilities/chains your client had access to at registration
  time. You are only notified for accounts belonging to those facilities.
• Members of a deactivated facility are not delivered.