Webhooks
Push data to Coach Watts via incoming webhooks for OAuth applications.
OAuth applications can push data to Coach Watts using incoming webhooks. This is useful when your integration receives data from external services and needs to forward it to Coach Watts without making direct API calls.
Webhook URL
Each registered application has a unique webhook endpoint:
POST https://coachwatts.com/api/webhooks/oauth/{clientId}
Replace {clientId} with your application's client ID from the Developer Portal.
You can copy the exact URL from your app's settings page in the portal.
Authentication
Webhooks are authenticated with a webhook secret configured on your application.
Send the secret using either:
- Header:
X-Webhook-Secret: your-secret - Query parameter:
?secret=your-secret
Generate or rotate the secret from your app's Webhook Secret section in the Developer Portal. Rotating invalidates the previous secret immediately.
Request format
Send a POST request with a JSON body. Coach Watts captures the raw payload and associates it with your application for asynchronous processing.
curl -X POST "https://coachwatts.com/api/webhooks/oauth/YOUR_CLIENT_ID" \
-H "Content-Type: application/json" \
-H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET" \
-d '{"event": "workout.completed", "data": { ... }}'
Response
{
"status": "success",
"message": "Data captured",
"receivedAt": "2026-07-11T12:00:00.000Z",
"secretMatched": true
}
The endpoint always returns 200 OK when the application exists, even if the secret does not match. Check secretMatched in the response to verify authentication.
A secretMatched: false response means your payload was logged but may not be processed. Fix your secret before relying on webhook delivery.
Viewing webhook logs
In the Developer Portal, open your application and view Webhook Logs to inspect:
- Received payloads and headers
- Secret match status
- Processing status
Use logs to debug integration issues during development.
When to use webhooks vs. the API
| Approach | Best for |
|---|---|
REST API (workout:write, health:write, etc.) | Structured, validated data uploads you control directly |
| Incoming webhooks | Relaying events from third-party systems that already send webhooks to your server |
For most integrations, the Syncing Data REST endpoints are preferred. Webhooks are a capture-and-process pipeline for raw event forwarding.