Webhooks let your application react to events happening in your Studio in real time. Instead of polling the Fitssey API, you register a callback URL and Fitssey sends an HTTP POST request to it every time a subscribed event occurs.

Webhooks can be configured in your Studio > Integrations > Webhooks.

This document covers webhooks. To read or change data in your Studio, see the API documentation.

Each webhook is delivered as an HTTP POST request with the following headers:

The request body is a JSON array containing a single event envelope:

[
  {
    "guid": "8F2B6C1D-4E7A-4B3C-9D21-5A6E7F8C9B0A",
    "webhookGuid": "3C9E1A7B-2D4F-4E8A-B6C0-1F5D9A2E7B43",
    "event": "event.shopping_cart.payment_status",
    "data": { ... },
    "firedAt": "2026-10-20T10:15:00+0200"
  }
]

Your callback URL accepts requests from anyone who knows it, so always verify that a request was really sent by Fitssey before acting on it. Each webhook has an authentication key and one of two authentication methods, selected in Studio > Integrations > Webhooks:

Every request is signed with the authentication key, so you can verify that it was sent by Fitssey and was not modified on the way. The key itself is never sent.

The Fitssey-Signature header contains a Unix timestamp and an HMAC-SHA256 signature:

Fitssey-Signature: t=1760954100,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

To verify the request:

1. Read the raw request body exactly as received, before parsing the JSON - any re-serialization changes the bytes and breaks the signature.
2. Split the header into t (timestamp) and v1 (signature).
3. Reject the request if t differs from the current time by more than 5 minutes to protect against replay attacks.
4. Compute the HMAC-SHA256 of the string {t}.{rawBody} using your authentication key as the key and encode it as lowercase hex.
5. Compare the result with v1 using a constant-time comparison.

The v1 prefix identifies the signature scheme. New schemes may be added in the future as additional vN entries, so ignore any you do not recognize.

PHP

$payload = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_FITSSEY_SIGNATURE'] ?? ''), $signature);

if(!isset($signature['t'], $signature['v1']) || 300 < abs(time() - (int) $signature['t']))
{
    http_response_code(400);
    exit;
}

$expected = hash_hmac('sha256', $signature['t'] . '.' . $payload, $secret);

if(!hash_equals($expected, $signature['v1']))
{
    http_response_code(401);
    exit;
}

$events = json_decode($payload, true);

Node.js (Express)

const crypto = require('crypto');

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const signature = Object.fromEntries((req.get('Fitssey-Signature') || '').split(',').map(part => part.split('=')));
    if(!signature.t || !signature.v1 || Math.abs(Date.now() / 1000 - signature.t) > 300) return res.sendStatus(400);

    const expected = crypto.createHmac('sha256', secret).update(`${signature.t}.${req.body}`).digest('hex');
    if(expected.length !== signature.v1.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature.v1))) return res.sendStatus(401);

    const events = JSON.parse(req.body);
    res.sendStatus(200);
});

The authentication key is sent as-is in the Fitssey-Secret header. Compare it with your key using a constant-time comparison and reject the request when it is missing or does not match:

if(!hash_equals($secret, $_SERVER['HTTP_FITSSEY_SECRET'] ?? ''))
{
    http_response_code(401);
    exit;
}

This method is meant for tools that cannot compute signatures, such as no-code automation platforms. Because the key travels with every request, it does not protect the body from modification, does not prevent replays and exposes the key to anything that logs the request. Use Signature whenever you can.

Respond with any 2xx status as quickly as possible and do the heavy processing asynchronously. Redirects are not followed.

The callback URL must be a public https address. URLs resolving to private or reserved IP ranges are rejected.

The connection timeout defaults to 5 seconds. Every failed delivery increases the webhook's fail counter; once it reaches the limit (5 by default) the webhook is suspended and stops receiving events until it is re-enabled. A successful delivery resets the counter. Failed deliveries are not retried.

The same change may be reported more than once, so processing a webhook twice must have the same effect as processing it once. Each event documents which fields identify a repeated change. The envelope guid is unique per event and is useful for logging, but two notifications about the same change carry different guid values, so it cannot be used to detect them.