Webhooks

Webhooks tell your integration what a client just did, so it can react right away instead of polling. You register a URL and TrainerStudio sends it a signed POST for each event you subscribe to.

Create an endpointCopy Anchor Link

In the coach app, go to Settings → Developers → Webhooks, add your URL and choose the events. Or use the API with your API key:

curl -X POST "https://api.trainerstudio.com/v2/coach/webhook-endpoints" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/trainerstudio",
    "description": "Coach agent",
    "eventTypes": ["chat.message_received", "workout.completed"]
  }'

The response includes secret (whsec_…). It is shown only once: store it. If you lose it, rotate the secret.

• The URL must be public https://, with no user name or password in it.
• "eventTypes": ["*"] subscribes to every event, including the ones added later.
• A company can have up to 10 endpoints.

EventsCopy Anchor Link

GET /v2/coach/webhook-event-types returns this catalog with an example payload per type.

PayloadCopy Anchor Link

{
  "id": "evt_6642f0c2a1b2c3d4e5f60718",
  "type": "workout.completed",
  "timestamp": "2026-11-13T09:30:00.000Z",
  "data": {
    "customerId": "60626cc191f3a274116fee34",
    "date": "2026-11-13",
    "completedItems": 6,
    "totalItems": 6
  }
}

Payloads carry ids, not content: no message text and no measurements. Read the details with the API or the MCP server using your own credentials.

Verify the signatureCopy Anchor Link

Every request carries three headers, as defined by Standard Webhooks:

The signature is the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the bytes your secret encodes after the whsec_ prefix.

The Standard Webhooks libraries (JavaScript, Python, Go, Ruby, PHP, Java, Rust, C#) do it for you:

import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.TRAINERSTUDIO_WEBHOOK_SECRET);

app.post("/webhooks/trainerstudio", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body, req.headers); // throws on a bad signature or an old timestamp
  } catch {
    return res.status(400).end();
  }
  res.status(204).end(); // acknowledge first
  enqueue(event); // then process
});

Or by hand:

import { createHmac, timingSafeEqual } from "node:crypto";

function isValid(secret, headers, rawBody) {
  const key = Buffer.from(secret.replace("whsec_", ""), "base64");
  const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${rawBody}`;
  const expected = Buffer.from(createHmac("sha256", key).update(signed).digest("base64"));
  const fresh = Math.abs(Date.now() / 1000 - Number(headers["webhook-timestamp"])) < 300;
  return (
    fresh &&
    headers["webhook-signature"].split(" ").some((signature) => {
      const candidate = Buffer.from(signature.replace("v1,", ""));
      return candidate.length === expected.length && timingSafeEqual(candidate, expected);
    })
  );
}

• Verify against the raw body, before any JSON parsing.
• Reject timestamps older than five minutes to stop replays.

Respond and retryCopy Anchor Link

• Answer with any 2xx within 10 seconds. Acknowledge first and do the work afterwards.
• Anything else is a failed attempt: other statuses, timeouts, connection errors. Redirects are not followed.
• A failed delivery is retried 8 times over about 28 hours: after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours. Retry-After is honored up to 24 hours.
• Delivery is at least once: the same event can arrive twice. Deduplicate on webhook-id.
• Order is not guaranteed. Use timestamp to order events.

Endpoint healthCopy Anchor Link

An endpoint is turned off, and its pending deliveries canceled, when:

• it answers 410 Gone, or
• every attempt has failed for 3 days.

Events that happen while an endpoint is off are not sent later. Turn it on again from Developers → Webhooks or with PATCH /v2/coach/webhook-endpoints/{id} and { "status": "enabled" }.

Rotate the secretCopy Anchor Link

POST /v2/coach/webhook-endpoints/{id}/secret-rotations returns a new secret. For 24 hours every delivery is signed with both the new and the old secret, so you can deploy the new one without rejecting events.

Test and debugCopy Anchor Link

• Send a test event from the endpoint's page, or POST /v2/coach/webhook-endpoints/{id}/test-events.
• The delivery log keeps every delivery for 30 days with its payload and each attempt: status code, duration, error and the start of your response. Also at GET /v2/coach/webhook-deliveries.
• Send again re-sends a finished delivery with the same event id: POST /v2/coach/webhook-deliveries/{id}/retries.
• GET /v2/coach/webhook-endpoints/{id}/stats returns success rate, average response time and daily counts.

APICopy Anchor Link

Only the account owner can manage webhooks.

Errors on these routes are application/problem+json with a stable code:

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The URL must be a public HTTPS address without a user name or password",
  "code": "webhook_url_not_allowed"
}