Skip to content

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in SweatStack, such as when activities are created, updated, or deleted.

Setting up webhooks

Webhooks can be configured in your API settings. You'll need to provide one or more webhook endpoints where SweatStack will send event notifications

A Webhook Secret is automatically generated when you create a new webhook. It is used to verify that webhook events are genuinely from SweatStack. You can regenerate (roll) the secret at any time, which will take effect immediately.

Event types

SweatStack sends webhook events for the following activity-related events:

  • activity_created - A new activity has been created
  • activity_updated - An existing activity has been updated
  • activity_deleted - An activity has been deleted

More event types will be added in the future.

Webhook payload

Each webhook event contains the following fields:

{
  "user_id": "string",
  "event_type": "activity_created",
  "resource_id": "string",
  "timestamp": "2024-01-01T12:00:00Z"
}

The resource_id is the ID of the activity that triggered the event. When more event types are added, the resource_id will be the ID of the resource that triggered the event.

The data of the resource that triggered the event is not included in the webhook payload and should be fetched using the appropriate endpoint.

Response time requirement

Your webhook endpoint must return a 2xx status code within 2 seconds to acknowledge receipt. Failed deliveries are automatically retried with exponential backoff until either a 2xx response is received or the retry delay exceeds 24 hours.

Verifying webhook signatures

All webhook events are cryptographically signed using HMAC-SHA256. The signature is included in the X-Sweatstack-Signature header with the format: t={timestamp},v1={signature}.

To verify the signature:

  1. Extract the timestamp and signature from the header
  2. Construct the signed payload: {timestamp}.{json_body}
  3. Compute HMAC-SHA256 using your webhook secret
  4. Compare signatures using constant-time comparison
  5. Optionally validate the timestamp to prevent replay attacks

Best practices

  • Verify signatures - Always verify the webhook signature before processing events
  • Return quickly - Acknowledge receipt with a 2xx status within 2 seconds, then process asynchronously
  • Log events - Keep logs of received webhooks for debugging and monitoring

Next steps

  • Configure your webhook in the API settings
  • Use the Activity data endpoint to fetch full activity details when you receive an event