Webhooks API

Running Days supports both inbound and outbound webhooks.

Inbound Webhooks

Health Auto Export Webhook

POST /api/webhook?token=YOUR_TOKEN

Receives workout data from the Health Auto Export iOS app.

Query Parameters: | Parameter | Type | Description | |-----------|------|-------------| | token | string | Webhook authentication token |

Request Body:

{
  "data": {
    "workouts": [
      {
        "name": "Running",
        "start": "2024-01-15T08:00:00Z",
        "end": "2024-01-15T08:30:00Z",
        "duration": 1800,
        "distance": 5000,
        "activeEnergy": 350,
        "avgHeartRate": 145,
        "maxHeartRate": 165
      }
    ]
  }
}

Response:

{
  "processed": 1,
  "skipped": 0,
  "message": "Successfully processed 1 workout(s)"
}

Supported Workout Types

The webhook accepts workouts with these names:

• Running
• Walking
• Hiking
• Trail Running

Deduplication

Workouts are deduplicated by:

1. Start time (within 1 minute tolerance)
2. Duration (within 10% tolerance)
3. Distance (within 5% tolerance)

Token Management

Generate Webhook Token

Tokens are generated in the app settings. Each token:

• Is a secure random string
• Can be revoked at any time
• Is stored hashed in the database

Testing Webhooks

curl -X POST "http://localhost:3000/api/webhook?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "workouts": [{
        "name": "Running",
        "start": "2024-01-15T08:00:00Z",
        "end": "2024-01-15T08:30:00Z",
        "duration": 1800,
        "distance": 5000
      }]
    }
  }'

Outbound Webhooks (Coming Soon)

Outbound webhooks will notify external services when events occur:

• workout.created - New workout imported
• goal.achieved - Yearly goal completed
• achievement.unlocked - Milestone reached
• streak.milestone - Streak milestone (7, 14, 30 days)

Webhook Payload Format

{
  "event": "achievement.unlocked",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "milestone": 100,
    "year": 2024,
    "completedDays": 100
  }
}

Retry Policy

Failed webhook deliveries will be retried:

• 3 attempts with exponential backoff
• 1 minute, 5 minutes, 30 minutes
• Failed after 3 attempts are logged for manual review