Documentation Index
Fetch the complete documentation index at: https://docs.saturday.fit/llms.txt
Use this file to discover all available pages before exploring further.
Webhooks
Webhooks let Saturday push real-time event notifications to your server. Instead of polling the API for changes, register a webhook URL and Saturday will POST events to you as they happen.Registering a webhook
Available events
| Event | Triggered when |
|---|---|
athlete.created | A new athlete is created |
athlete.updated | An athlete profile is modified |
athlete.deleted | An athlete is deleted |
activity.created | A new activity is created |
activity.updated | An activity is modified |
prescription.calculated | A nutrition prescription is generated |
feedback.submitted | Post-activity feedback is submitted |
subscription.activated | An athlete subscribes to Saturday |
subscription.canceled | An athlete’s subscription is canceled |
conversation.message_sent | An AI Coach message is sent |
Webhook payload format
Every webhook delivery has this structure:Verifying webhook signatures (HMAC-SHA256)
Every webhook delivery includes a signature in theX-Saturday-Signature header. Always verify this signature to confirm the webhook came from Saturday and wasn’t tampered with.
The signature is computed as HMAC-SHA256(webhook_secret, timestamp + "." + raw_body).
Verification steps
- Extract the timestamp and signature from the header
- Reconstruct the signed payload:
{timestamp}.{raw_body} - Compute HMAC-SHA256 using your webhook secret
- Compare with constant-time equality
Retry behavior
If your endpoint fails (non-2xx response or timeout), Saturday retries with exponential backoff:| Attempt | Delay | Total elapsed |
|---|---|---|
| 1st retry | 30 seconds | 30s |
| 2nd retry | 2 minutes | 2.5 min |
| 3rd retry | 10 minutes | 12.5 min |
| 4th retry | 1 hour | 1 hr 12.5 min |
| 5th retry | 4 hours | 5 hr 12.5 min |
Auto-disable
If a webhook endpoint fails consistently for 3 consecutive days, Saturday automatically disables it and sends a notification email to the partner contact. Re-enable it from the API after fixing the issue:Best practices
- Return 200 immediately — process events asynchronously. Saturday times out after 30 seconds.
- Handle duplicates — use the
idfield to deduplicate. The same event may be delivered more than once. - Verify signatures — always. Never trust a webhook payload without HMAC verification.
- Use HTTPS — Saturday only delivers to HTTPS endpoints.
- Log everything — store raw payloads for debugging. Include the event
idin your logs.