Lead Webhooks

Receive the record for a known viewer. Use it to create or update a contact in your application. Mindstamp treats a viewer as known when it has an email address, phone number, custom ID, or a name that is not an anonymous display name.

The JSON uses id, name, email, phone, and custom_id. The viewer_ prefix belongs to the view and interaction payloads.

See Webhooks for setup and delivery handling.

Example POST body

This complete example contains a fictional viewer with an email address and a custom employee ID. A lead can have a null email address.

{
  "created_at": "2026-09-08T14:00:00.000Z",
  "name": "Alex Morgan",
  "email": "[email protected]",
  "phone": null,
  "owner_id": "20000000-0000-4000-8000-000000000001",
  "user_id": null,
  "custom_id": "employee-1042",
  "stats_views": 1,
  "stats_interactions": 2,
  "stats_streaming": 120,
  "stats_engagement": 120,
  "variables": {
    "department": "Operations",
    "course_id": "safety-intro"
  },
  "updated_at": "2026-09-08T14:02:00.000Z",
  "id": "50000000-0000-4000-8000-000000000001",
  "group_id": "30000000-0000-4000-8000-000000000001",
  "group_name": "New employee training"
}

Use this payload

Use id as the Mindstamp viewer key. If your application supplied custom_id, use it to find the existing customer or learner. Use email only when it is present and your application uses it as an identifier.

const contact = {
  mindstampViewerId: body.id,
  externalId: body.custom_id,
  name: body.name,
  email: body.email,
  phone: body.phone,
  department: body.variables?.department ?? null
};
// Create or update the contact. Keep the Mindstamp viewer ID on the record.

Link a lead to later activity

Lead field	Matching field in a view or interaction
`id`	`viewer_id`
`custom_id`	`viewer_custom_id`
`email`	`viewer_email`
`name`	`viewer_name`
`phone`	`viewer_phone`

The lead body does not include a video_id, view_id, question response, or completion score. Use view and interaction webhooks for those fields. Match records by viewer ID, even if the requests arrive in a different order.

Field reference

The stats_* fields are stored totals. Mindstamp updates them in a background job, so they can lag behind the event that caused delivery. Do not use them to confirm one view's completion.

Field	JSON type	Description
`created_at`	string	Time Mindstamp created the viewer record, as an ISO 8601 timestamp.
`name`	string or null	Viewer name. A lead can have a name without an email address.
`email`	string or null	Viewer email, when available.
`phone`	string or null	Viewer phone, when available.
`owner_id`	string or null	Owner ID stored on the viewer.
`user_id`	string or null	Associated user ID, when stored. This is separate from the viewer ID.
`custom_id`	string or null	Your identifier for the viewer, when supplied.
`stats_views`	integer	Stored total view count for this viewer.
`stats_interactions`	integer	Stored total interaction count across the viewer's views.
`stats_streaming`	integer	Stored sum of tracked video seconds across the viewer's views.
`stats_engagement`	integer	Stored engagement time in seconds. The current calculation uses the larger of total elapsed time and total tracked video seconds. This is not a percentage.
`variables`	object or null	Stored variables. Values can have different JSON types. Privacy settings can remove values. The lowercase setting can change key names.
`updated_at`	string	Viewer record update time at serialization. This is not a delivery timestamp.
`id`	string	Viewer ID. Matches viewer_id in view and interaction webhooks.
`group_id`	string or null	Group ID from the video associated with the viewer record. It can differ from the video that triggered delivery.
`group_name`	string or null	Name of that group, when available.

Delivery behavior

Mindstamp checks lead delivery during view post-processing. The current sender skips unknown viewers and viewers whose lead webhook already succeeded. It stores success on the viewer record, across videos and destination URLs. Use view webhooks to track returning viewers or later changes in their recorded activity.