Session Alert Webhooks

Access required

The company must have Session Activity Notifications, API Access and Webhooks. A tenant owner or user with Manage Session Notifications can configure the endpoint. Open Session Alerts from the main navigation.

Set up the webhook

1. Build a receiving endpoint that accepts an HTTPS POST on public port 443.
2. Open Session Alerts, choose Set up beside Webhook and enter the endpoint URL.
3. Select session.started, session.stopped, or both, and enable the endpoint.
4. Save and immediately copy the generated wpwh_ signing secret. The full secret is shown only once.
5. Store the secret in your server's protected environment or secret manager.
6. Choose Test webhook and confirm the delivery is marked Delivered.
7. Turn on the page's global Live alerts switch, select the same live events there, and save the alert settings.
8. Start and stop one real work session and confirm both the receiving system and Recent deliveries.

Settings reference

Request headers

Example session.started payload

{
  "id": "019f1234-5678-7abc-9def-0123456789ab",
  "type": "session.started",
  "occurred_at": "2026-08-23T09:15:00Z",
  "tenant": {
    "id": "019d1234-5678-7abc-9def-0123456789ab",
    "name": "Example Company"
  },
  "user": {
    "id": "019e1234-5678-7abc-9def-0123456789ab",
    "name": "Example Employee",
    "email": "employee@example.com"
  },
  "session": {
    "id": 321,
    "start_time": "2026-08-23T09:15:00Z",
    "end_time": null,
    "duration_seconds": null,
    "team": {"id": 4, "name": "Operations"},
    "project": {"id": 18, "name": "Client work"},
    "session_type": {"id": 1, "name": "Desktop"},
    "auto_closed": false,
    "closure_reason": null
  },
  "is_test": false,
  "delivery": {"attempt": 1, "replay": false},
  "schema_version": "1.0"
}

Team or project can be null when the matching inclusion setting is off or the session has no value. A stopped event includes end_time, duration_seconds, and automatic-closure context.

Verify the signature

Read the request as raw bytes before parsing JSON. Join the timestamp, one period and the exact raw body, then calculate a hexadecimal HMAC-SHA256 with the signing secret.

signed_value = X-Workpulse-Timestamp + "." + exact_raw_request_body
expected = "v1=" + HMAC_SHA256_HEX(signing_secret, signed_value)

1. Reject the request if the timestamp is missing, invalid or older than five minutes.
2. Calculate the expected value from the unmodified raw body.
3. Compare the expected and supplied signatures with a constant-time comparison.
4. Only then parse and process the JSON.
5. Do not log the signing secret or full sensitive payloads.

Responses, retries and duplicates

• Return any 2xx response within 10 seconds to mark the delivery successful.
• Redirects are not followed.
• HTTP 408, 425, 429 and 5xx responses are retried after approximately 60 seconds, 5 minutes and 30 minutes, for up to four attempts.
• Other 4xx responses are terminal failures and can be replayed from Recent deliveries after the problem is corrected.
• Use the event ID or Idempotency-Key to make repeated attempts safe. A manual replay retains the event ID and sets delivery.replay to true.
• An endpoint is automatically paused after 20 consecutive failures. Correct the receiver, re-enable it and send a test.

Troubleshooting