> ## 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.

# Event Payloads

> Full payload schemas for every Zenstep webhook event type.

## Payload structure

All webhook payloads share a common envelope:

```typescript theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "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"
  }
}
```

<Note>
  `userHash` is a HMAC-SHA256 hash of the `userId` passed to `identify()`. The
  raw user ID is never sent in webhook payloads.
</Note>

***

## flow\.dismissed

Fired when a user explicitly dismisses a flow (clicks the X or "Skip" button).

```json theme={null}
{
  "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

| Field       | Type     | Description                                                      |
| ----------- | -------- | ---------------------------------------------------------------- |
| `flowId`    | `string` | UUID of the flow                                                 |
| `flowName`  | `string` | Display name of the flow                                         |
| `flowType`  | `string` | One of: `hint`, `tour_step`, `modal_step`, `checklist`, `banner` |
| `stepId`    | `string` | UUID of the step (where applicable)                              |
| `userHash`  | `string` | HMAC-SHA256 hash of the `userId`                                 |
| `sessionId` | `string` | Browser session identifier                                       |
| `pageUrl`   | `string` | Full URL where the event occurred                                |
| `orgId`     | `string` | Your Zenstep organisation ID                                     |