Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getzenstep.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Payload structure

All webhook payloads share a common envelope: 
interface WebhookPayload {
  id: string; // Unique delivery ID (UUID)
  event: string; // Event type (e.g. "step.broken")
  timestamp: string; // ISO 8601 timestamp
  data: object; // Event-specific data
}

​
step.broken

Fired when Zenstep’s Smart Anchoring engine cannot find the DOM element for a step after multiple consecutive page loads. 
{
  "id": "wh_01HX3K8N2P4Q6R7S8T9U0V1W2",
  "event": "step.broken",
  "timestamp": "2024-09-15T14:23:01.000Z",
  "data": {
    "stepId": "step_abc123",
    "stepName": "Click the Export button",
    "flowId": "flow_xyz789",
    "flowName": "Analytics Onboarding",
    "health": "broken",
    "fingerprint": {
      "testId": "btn-export",
      "ariaLabel": "Export CSV",
      "textContent": "Export",
      "cssSelector": "#analytics-panel > button.export-btn",
      "xpath": "/html/body/main/section[2]/button",
      "parentContext": {
        "tag": "section",
        "textSample": "Analytics Panel"
      }
    },
    "orgId": "org_123abc",
    "reportedAt": "2024-09-15T14:23:00.000Z"
  }
}

​
step.recovered

Fired when a previously broken step is successfully anchored again. 
{
  "id": "wh_01HX3K8N2P4Q6R7S8T9U0V1W3",
  "event": "step.recovered",
  "timestamp": "2024-09-16T09:10:22.000Z",
  "data": {
    "stepId": "step_abc123",
    "stepName": "Click the Export button",
    "flowId": "flow_xyz789",
    "flowName": "Analytics Onboarding",
    "health": "recovered",
    "orgId": "org_123abc",
    "reportedAt": "2024-09-16T09:10:21.000Z"
  }
}

​
flow.completed

Fired when a user completes a flow (reaches the last step and confirms). 
{
  "id": "wh_01HX3K8N2P4Q6R7S8T9U0V1W4",
  "event": "flow.completed",
  "timestamp": "2024-09-15T15:45:33.000Z",
  "data": {
    "flowId": "flow_xyz789",
    "flowName": "Analytics Onboarding",
    "flowType": "tour_step",
    "userHash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
    "sessionId": "sess_def456",
    "pageUrl": "https://app.example.com/analytics",
    "completedAt": "2024-09-15T15:45:32.000Z"
  }
}
userHash is a HMAC-SHA256 hash of the userId passed to identify(). The raw user ID is never sent in webhook payloads.

​
flow.dismissed

Fired when a user explicitly dismisses a flow (clicks the X or “Skip” button). 
{
  "id": "wh_01HX3K8N2P4Q6R7S8T9U0V1W5",
  "event": "flow.dismissed",
  "timestamp": "2024-09-15T16:02:11.000Z",
  "data": {
    "flowId": "flow_xyz789",
    "flowName": "Analytics Onboarding",
    "flowType": "tour_step",
    "stepId": "step_abc123",
    "userHash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
    "sessionId": "sess_def456",
    "pageUrl": "https://app.example.com/analytics",
    "dismissedAt": "2024-09-15T16:02:10.000Z"
  }
}

​
Common data fields

FieldTypeDescription
flowIdstringUUID of the flow
flowNamestringDisplay name of the flow
flowTypestringOne of: hint, tour_step, modal_step, checklist, banner
stepIdstringUUID of the step (where applicable)
userHashstringHMAC-SHA256 hash of the userId
sessionIdstringBrowser session identifier
pageUrlstringFull URL where the event occurred
orgIdstringYour Zenstep organisation ID