Webhook events

Every outgoing webhook event type with its payload schema and an example, generated from the OpenAPI document.

Every event is delivered as a POST with the envelope below the data key, signed as described in verifying signatures. Subscribe to event types per endpoint in Developers → Webhooks. New event types may be added at any time; ignore types you don't know.

Event	Sent when
`action.executed`	An order action the shopper confirmed (cancel, return, address change) was executed on the platform.
`back_in_stock.notified`	A back-in-stock alert was sent to the shopper.
`back_in_stock.subscribed`	A shopper subscribed to a back-in-stock alert.
`conversation.closed`	A conversation was closed by the shopper, an agent or after the idle timeout.
`conversation.created`	A shopper started a conversation.
`csat.submitted`	A shopper rated a conversation.
`handoff.requested`	A conversation was handed off to your team; the payload carries up to 50 transcript messages.
`handoff.updated`	A handoff changed state (taken over, delivered, resolved, failed).
`lead.captured`	A shopper left contact details in the chat.
`lead.confirmed`	A shopper confirmed their newsletter sign-up (double opt-in).
`lead.unsubscribed`	A shopper unsubscribed.
`message.created`	A message was added to a conversation. Opt-in and high volume.
`order.attributed`	An order was attributed to a conversation.
`privacy_request.completed`	A privacy request (export or erasure) finished.
`store.status_changed`	A store changed status (for example connected, disconnected, suspended).
`sync.failed`	A catalog sync run failed.
`usage.threshold_reached`	Usage reached 80 % or 100 % of the included conversations, or the overage budget.

`action.executed`

An order action the shopper confirmed (cancel, return, address change) was executed on the platform.

Sent with ShopAssist-Event-Type: action.executed. Acknowledge with any 2xx within 10 seconds.

Payload of action.executed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	ActionExecutedData	`{ action; conversation_id }`.
data.actionrequired	ActionEventView	`{ id; action_type; mode; status; order_number; result; created_at; executed_at }`.
data.action.action_typerequired	"cancel_order" \| "cancellation_request" \| "return_order" \| "return_request"
data.action.created_atrequired	string	format date-time
data.action.executed_atrequired	string \| null	format date-time
data.action.idrequired	string	pattern `^act_[0-9a-hjkmnp-tv-z]{26}$`
data.action.moderequired	"direct" \| "request_only" \| "platform_self_service" \| "platform"
data.action.order_numberrequired	string \| null
data.action.resultrequired	object \| null
data.action.statusrequired	string (enum)	one of proposed, executing, succeeded, requested, failed, declined, expired, superseded
data.conversation_idrequired	string	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"action.executed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "action": {
      "action_type": "cancel_order",
      "created_at": "2026-09-28T10:15:30.123Z",
      "executed_at": "2026-09-28T10:15:30.123Z",
      "id": "act_01j8000000e008000000000000",
      "mode": "direct",
      "order_number": "string",
      "result": {},
      "status": "proposed"
    },
    "conversation_id": "conv_01j8000000e008000000000000"
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "action.executed"
}

`back_in_stock.notified`

A back-in-stock alert was sent to the shopper.

Sent with ShopAssist-Event-Type: back_in_stock.notified. Acknowledge with any 2xx within 10 seconds.

Payload of back_in_stock.notified
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	BackInStockEventData	`{ subscription: BackInStock }`.
data.subscriptionrequired	BackInStock	`BackInStock` (03 §6.19).
data.subscription.created_atrequired	string	format date-time
data.subscription.emailrequired	string
data.subscription.expires_atrequired	string	format date-time
data.subscription.idrequired	string	pattern `^bis_[0-9a-hjkmnp-tv-z]{26}$`
data.subscription.localerequired	string
data.subscription.location_idrequired	string \| null	pattern `^loc_[0-9a-hjkmnp-tv-z]{26}$`
data.subscription.notified_atrequired	string \| null	format date-time
data.subscription.product_idrequired	string	pattern `^prd_[0-9a-hjkmnp-tv-z]{26}$`
data.subscription.statusrequired	"pending_confirmation" \| "active" \| "notified" \| "cancelled" \| "expired"
data.subscription.variant_idrequired	string	pattern `^var_[0-9a-hjkmnp-tv-z]{26}$`
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"back_in_stock.notified"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "subscription": {
      "created_at": "2026-09-28T10:15:30.123Z",
      "email": "string",
      "expires_at": "2026-09-28T10:15:30.123Z",
      "id": "bis_01j8000000e008000000000000",
      "locale": "da-DK",
      "location_id": "loc_01j8000000e008000000000000",
      "notified_at": "2026-09-28T10:15:30.123Z",
      "product_id": "prd_01j8000000e008000000000000",
      "status": "pending_confirmation",
      "variant_id": "var_01j8000000e008000000000000"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "back_in_stock.notified"
}

`back_in_stock.subscribed`

A shopper subscribed to a back-in-stock alert.

Sent with ShopAssist-Event-Type: back_in_stock.subscribed. Acknowledge with any 2xx within 10 seconds.

Payload of back_in_stock.subscribed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	BackInStockEventData	`{ subscription: BackInStock }`.
data.subscriptionrequired	BackInStock	`BackInStock` (03 §6.19).
data.subscription.created_atrequired	string	format date-time
data.subscription.emailrequired	string
data.subscription.expires_atrequired	string	format date-time
data.subscription.idrequired	string	pattern `^bis_[0-9a-hjkmnp-tv-z]{26}$`
data.subscription.localerequired	string
data.subscription.location_idrequired	string \| null	pattern `^loc_[0-9a-hjkmnp-tv-z]{26}$`
data.subscription.notified_atrequired	string \| null	format date-time
data.subscription.product_idrequired	string	pattern `^prd_[0-9a-hjkmnp-tv-z]{26}$`
data.subscription.statusrequired	"pending_confirmation" \| "active" \| "notified" \| "cancelled" \| "expired"
data.subscription.variant_idrequired	string	pattern `^var_[0-9a-hjkmnp-tv-z]{26}$`
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"back_in_stock.subscribed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "subscription": {
      "created_at": "2026-09-28T10:15:30.123Z",
      "email": "string",
      "expires_at": "2026-09-28T10:15:30.123Z",
      "id": "bis_01j8000000e008000000000000",
      "locale": "da-DK",
      "location_id": "loc_01j8000000e008000000000000",
      "notified_at": "2026-09-28T10:15:30.123Z",
      "product_id": "prd_01j8000000e008000000000000",
      "status": "pending_confirmation",
      "variant_id": "var_01j8000000e008000000000000"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "back_in_stock.subscribed"
}

`conversation.closed`

A conversation was closed by the shopper, an agent or after the idle timeout.

Sent with ShopAssist-Event-Type: conversation.closed. Acknowledge with any 2xx within 10 seconds.

Payload of conversation.closed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	ConversationEventData	`{ conversation: ApiConversation }`.
data.conversationrequired	ApiConversation	`ConversationSummary` without `last_message_preview`, plus `platform_customer_id`.
data.conversation.assigned_user_idrequired	string \| null	pattern `^usr_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.channelrequired	"widget" \| "playground" \| "preview" \| "demo" \| "api"
data.conversation.closed_atrequired	string \| null	format date-time
data.conversation.csat_scorerequired	integer \| null
data.conversation.handoff_requested_atrequired	string \| null	format date-time
data.conversation.handoff_staterequired	"none" \| "requested" \| "live" \| "delivered_offline" \| "failed" \| "resolved"
data.conversation.idrequired	string	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.identity_levelrequired	"guest" \| "order_lookup" \| "order_otp" \| "customer"
data.conversation.is_testrequired	boolean
data.conversation.last_message_atrequired	string \| null	format date-time
data.conversation.localerequired	string \| null
data.conversation.message_countrequired	integer	≥ 0
data.conversation.moderequired	"ai" \| "human_requested" \| "human"
data.conversation.platform_customer_idrequired	string \| null	Only for identity_level = customer
data.conversation.resolutionrequired	"resolved_ai" \| "handed_off" \| "abandoned" \| "unknown" \| null
data.conversation.shopperrequired	ShopperView	Shopper identity as shown on lists (masked for agent/viewer, 06 §5.3).
data.conversation.shopper.emailrequired	string \| null
data.conversation.shopper.is_maskedrequired	boolean
data.conversation.shopper.is_verifiedrequired	boolean
data.conversation.shopper.namerequired	string \| null
data.conversation.started_atrequired	string	format date-time
data.conversation.statusrequired	"open" \| "closed"
data.conversation.store_idrequired	string	pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.tagsrequired	string[]
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"conversation.closed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "conversation": {
      "assigned_user_id": "usr_01j8000000e008000000000000",
      "channel": "widget",
      "closed_at": "2026-09-28T10:15:30.123Z",
      "csat_score": 1,
      "handoff_requested_at": "2026-09-28T10:15:30.123Z",
      "handoff_state": "none",
      "id": "conv_01j8000000e008000000000000",
      "identity_level": "guest",
      "is_test": true,
      "last_message_at": "2026-09-28T10:15:30.123Z",
      "locale": "da-DK",
      "message_count": 0,
      "mode": "ai",
      "platform_customer_id": "string",
      "resolution": "resolved_ai",
      "shopper": {
        "email": "string",
        "is_masked": true,
        "is_verified": true,
        "name": "string"
      },
      "started_at": "2026-09-28T10:15:30.123Z",
      "status": "open",
      "store_id": "sto_01j8000000e008000000000000",
      "tags": [
        "string"
      ]
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "conversation.closed"
}

`conversation.created`

A shopper started a conversation.

Sent with ShopAssist-Event-Type: conversation.created. Acknowledge with any 2xx within 10 seconds.

Payload of conversation.created
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	ConversationEventData	`{ conversation: ApiConversation }`.
data.conversationrequired	ApiConversation	`ConversationSummary` without `last_message_preview`, plus `platform_customer_id`.
data.conversation.assigned_user_idrequired	string \| null	pattern `^usr_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.channelrequired	"widget" \| "playground" \| "preview" \| "demo" \| "api"
data.conversation.closed_atrequired	string \| null	format date-time
data.conversation.csat_scorerequired	integer \| null
data.conversation.handoff_requested_atrequired	string \| null	format date-time
data.conversation.handoff_staterequired	"none" \| "requested" \| "live" \| "delivered_offline" \| "failed" \| "resolved"
data.conversation.idrequired	string	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.identity_levelrequired	"guest" \| "order_lookup" \| "order_otp" \| "customer"
data.conversation.is_testrequired	boolean
data.conversation.last_message_atrequired	string \| null	format date-time
data.conversation.localerequired	string \| null
data.conversation.message_countrequired	integer	≥ 0
data.conversation.moderequired	"ai" \| "human_requested" \| "human"
data.conversation.platform_customer_idrequired	string \| null	Only for identity_level = customer
data.conversation.resolutionrequired	"resolved_ai" \| "handed_off" \| "abandoned" \| "unknown" \| null
data.conversation.shopperrequired	ShopperView	Shopper identity as shown on lists (masked for agent/viewer, 06 §5.3).
data.conversation.shopper.emailrequired	string \| null
data.conversation.shopper.is_maskedrequired	boolean
data.conversation.shopper.is_verifiedrequired	boolean
data.conversation.shopper.namerequired	string \| null
data.conversation.started_atrequired	string	format date-time
data.conversation.statusrequired	"open" \| "closed"
data.conversation.store_idrequired	string	pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.tagsrequired	string[]
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"conversation.created"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "conversation": {
      "assigned_user_id": "usr_01j8000000e008000000000000",
      "channel": "widget",
      "closed_at": "2026-09-28T10:15:30.123Z",
      "csat_score": 1,
      "handoff_requested_at": "2026-09-28T10:15:30.123Z",
      "handoff_state": "none",
      "id": "conv_01j8000000e008000000000000",
      "identity_level": "guest",
      "is_test": true,
      "last_message_at": "2026-09-28T10:15:30.123Z",
      "locale": "da-DK",
      "message_count": 0,
      "mode": "ai",
      "platform_customer_id": "string",
      "resolution": "resolved_ai",
      "shopper": {
        "email": "string",
        "is_masked": true,
        "is_verified": true,
        "name": "string"
      },
      "started_at": "2026-09-28T10:15:30.123Z",
      "status": "open",
      "store_id": "sto_01j8000000e008000000000000",
      "tags": [
        "string"
      ]
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "conversation.created"
}

`csat.submitted`

A shopper rated a conversation.

Sent with ShopAssist-Event-Type: csat.submitted. Acknowledge with any 2xx within 10 seconds.

Payload of csat.submitted
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	CsatSubmittedData	`{ conversation_id; score; comment }`.
data.commentrequired	string \| null
data.conversation_idrequired	string	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.scorerequired	integer	≥ 1 · ≤ 5
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"csat.submitted"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "comment": "string",
    "conversation_id": "conv_01j8000000e008000000000000",
    "score": 1
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "csat.submitted"
}

`handoff.requested`

A conversation was handed off to your team; the payload carries up to 50 transcript messages.

Sent with ShopAssist-Event-Type: handoff.requested. Acknowledge with any 2xx within 10 seconds.

Payload of handoff.requested
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	HandoffRequestedData	`{ handoff; conversation; transcript (≤ 50); dashboard_url }` (`handoff.shopper` carries `identity_level` and `email_verified`).
data.conversationrequired	ApiConversation	`ConversationSummary` without `last_message_preview`, plus `platform_customer_id`.
data.conversation.assigned_user_idrequired	string \| null	pattern `^usr_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.channelrequired	"widget" \| "playground" \| "preview" \| "demo" \| "api"
data.conversation.closed_atrequired	string \| null	format date-time
data.conversation.csat_scorerequired	integer \| null
data.conversation.handoff_requested_atrequired	string \| null	format date-time
data.conversation.handoff_staterequired	"none" \| "requested" \| "live" \| "delivered_offline" \| "failed" \| "resolved"
data.conversation.idrequired	string	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.identity_levelrequired	"guest" \| "order_lookup" \| "order_otp" \| "customer"
data.conversation.is_testrequired	boolean
data.conversation.last_message_atrequired	string \| null	format date-time
data.conversation.localerequired	string \| null
data.conversation.message_countrequired	integer	≥ 0
data.conversation.moderequired	"ai" \| "human_requested" \| "human"
data.conversation.platform_customer_idrequired	string \| null	Only for identity_level = customer
data.conversation.resolutionrequired	"resolved_ai" \| "handed_off" \| "abandoned" \| "unknown" \| null
data.conversation.shopperrequired	ShopperView	Shopper identity as shown on lists (masked for agent/viewer, 06 §5.3).
data.conversation.shopper.emailrequired	string \| null
data.conversation.shopper.is_maskedrequired	boolean
data.conversation.shopper.is_verifiedrequired	boolean
data.conversation.shopper.namerequired	string \| null
data.conversation.started_atrequired	string	format date-time
data.conversation.statusrequired	"open" \| "closed"
data.conversation.store_idrequired	string	pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
data.conversation.tagsrequired	string[]
data.dashboard_urlrequired	string	format uri · ≤ 2048 characters
data.handoffrequired	HandoffAdmin	`HandoffAdmin = HandoffState & {…}` (03 §6).
data.handoff.accepted_atrequired	string \| null	format date-time
data.handoff.agentrequired	AgentRef \| null
data.handoff.agent.display_namerequired	string
data.handoff.delivered_atrequired	string \| null	format date-time
data.handoff.expected_wait_secondsrequired	integer \| null
data.handoff.idrequired	string	pattern `^hof_[0-9a-hjkmnp-tv-z]{26}$`
data.handoff.messagerequired	string	Localized shopper-facing status text
data.handoff.reasonrequired	string (enum)	one of shopper_request, ai_escalation, action_request, policy, repeated_failure, error, outside_hours, quota_block, limit_reached
data.handoff.requested_atrequired	string	format date-time
data.handoff.requested_byrequired	"shopper" \| "ai" \| "agent" \| "system"
data.handoff.shopperrequired	HandoffShopper	`HandoffAdmin.shopper` (`platform_customer_id` only for `identity_level = customer`).
data.handoff.shopper.emailrequired	string \| null
data.handoff.shopper.email_verifiedrequired	boolean
data.handoff.shopper.identity_levelrequired	"guest" \| "order_lookup" \| "order_otp" \| "customer"
data.handoff.shopper.namerequired	string \| null
data.handoff.shopper.platform_customer_idrequired	string \| null
data.handoff.staterequired	"requested" \| "waiting_for_agent" \| "live" \| "delivered_offline" \| "failed" \| "resolved"
data.handoff.statusrequired	string (enum)	one of requested, waiting_for_agent, live, delivering, delivered, failed, resolved, cancelled
data.handoff.summaryrequired	string \| null
data.handoff.targetrequired	"live_chat" \| "email" \| "helpdesk" \| null
data.handoff.targetsrequired	HandoffTargetView[]
data.handoff.targets[].external_urlrequired	string \| null	format uri · ≤ 2048 characters
data.handoff.targets[].integration_idrequired	string \| null	pattern `^int_[0-9a-hjkmnp-tv-z]{26}$`
data.handoff.targets[].last_errorrequired	string \| null
data.handoff.targets[].statusrequired	"pending" \| "delivered" \| "failed" \| "skipped"
data.handoff.targets[].typerequired	string
data.transcriptrequired	ApiMessage[]	≤ 50 items
data.transcript[].authorrequired	MessageAuthor	Who wrote a message.
data.transcript[].author.display_namerequired	string \| null
data.transcript[].author.typerequired	"shopper" \| "ai" \| "human" \| "system"
data.transcript[].blocksrequired	UiBlock[]
data.transcript[].created_atrequired	string	format date-time
data.transcript[].idrequired	string	pattern `^msg_[0-9a-hjkmnp-tv-z]{26}$`
data.transcript[].is_ai_generatedrequired	boolean
data.transcript[].rolerequired	"shopper" \| "assistant" \| "agent" \| "system"
data.transcript[].seqrequired	integer	≥ 0
data.transcript[].textrequired	string
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"handoff.requested"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "conversation": {
      "assigned_user_id": "usr_01j8000000e008000000000000",
      "channel": "widget",
      "closed_at": "2026-09-28T10:15:30.123Z",
      "csat_score": 1,
      "handoff_requested_at": "2026-09-28T10:15:30.123Z",
      "handoff_state": "none",
      "id": "conv_01j8000000e008000000000000",
      "identity_level": "guest",
      "is_test": true,
      "last_message_at": "2026-09-28T10:15:30.123Z",
      "locale": "da-DK",
      "message_count": 0,
      "mode": "ai",
      "platform_customer_id": "string",
      "resolution": "resolved_ai",
      "shopper": {
        "email": "string",
        "is_masked": true,
        "is_verified": true,
        "name": "string"
      },
      "started_at": "2026-09-28T10:15:30.123Z",
      "status": "open",
      "store_id": "sto_01j8000000e008000000000000",
      "tags": [
        "string"
      ]
    },
    "dashboard_url": "https://shop.example/products/linen-shirt",
    "handoff": {
      "agent": null,
      "expected_wait_seconds": 120,
      "id": "hof_01j8000000e008000000000001",
      "message": "We've let the team know. Someone will be with you shortly.",
      "state": "waiting_for_agent",
      "target": "live_chat"
    },
    "transcript": [
      {
        "author": {
          "display_name": "string",
          "type": "shopper"
        },
        "blocks": [
          {
            "as_of": "2026-09-28T10:15:30.123Z",
            "id": "b1",
            "items": [
              {
                "actions": {
                  "add_to_cart": true,
                  "check_store_stock": true,
                  "notify_back_in_stock": false
                },
                "as_of": "2026-09-28T10:15:30.123Z",
                "availability": {
                  "as_of": "2026-09-28T10:15:30.123Z",
                  "label": "Only 2 left",
                  "quantity": 2,
                  "status": "low_stock"
                },
                "badges": [
                  "New"
                ],
                "default_variant_id": "var_01j8000000e008000000000001",
                "image": {
                  "alt": "City bike",
                  "height": 600,
                  "url": "https://cdn.shopify.com/s/files/1/demo/bike-1.jpg",
                  "width": 800
                },
                "options": [
                  {
                    "name": "Size",
                    "values": [
                      {
                        "is_available": true,
                        "value": "M"
                      },
                      {
                        "is_available": false,
                        "value": "L"
                      }
                    ]
                  }
                ],
                "price": {
                  "amount": "4999",
                  "currency": "DKK",
                  "display": "4.999,00 kr."
                },
                "product_id": "prd_01j8000000e008000000000001",
                "rating": {
                  "average": 4.6,
                  "count": 128
                },
                "subtitle": "Nordic Bikes",
                "title": "Nordic City Bike 7-speed",
                "url": "https://nordicbikes.example/products/city-bike?utm_source=shopassist&utm_medium=chat",
                "variants": [
                  {
                    "availability": {
                      "as_of": "2026-09-28T10:15:30.123Z",
                      "label": "Only 2 left",
                      "quantity": 2,
                      "status": "low_stock"
                    },
                    "cart_ref": {
                      "variant_gid": "gid://shopify/ProductVariant/4711"
                    },
                    "options": {
                      "Size": "M"
                    },
                    "price": {
                      "amount": "4999",
                      "currency": "DKK",
                      "display": "4.999,00 kr."
                    },
                    "title": "M",
                    "variant_id": "var_01j8000000e008000000000001"
                  }
                ]
              }
            ],
            "layout": "carousel",
            "title": "City bikes in stock",
            "type": "products"
          }
        ],
        "created_at": "2026-09-28T10:15:30.123Z",
        "id": "msg_01j8000000e008000000000000",
        "is_ai_generated": true,
        "role": "shopper",
        "seq": 0,
        "text": "string"
      }
    ]
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "handoff.requested"
}

`handoff.updated`

A handoff changed state (taken over, delivered, resolved, failed).

Sent with ShopAssist-Event-Type: handoff.updated. Acknowledge with any 2xx within 10 seconds.

Payload of handoff.updated
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	HandoffUpdatedData	`{ handoff: HandoffAdmin }`.
data.handoffrequired	HandoffAdmin	`HandoffAdmin = HandoffState & {…}` (03 §6).
data.handoff.accepted_atrequired	string \| null	format date-time
data.handoff.agentrequired	AgentRef \| null
data.handoff.agent.display_namerequired	string
data.handoff.delivered_atrequired	string \| null	format date-time
data.handoff.expected_wait_secondsrequired	integer \| null
data.handoff.idrequired	string	pattern `^hof_[0-9a-hjkmnp-tv-z]{26}$`
data.handoff.messagerequired	string	Localized shopper-facing status text
data.handoff.reasonrequired	string (enum)	one of shopper_request, ai_escalation, action_request, policy, repeated_failure, error, outside_hours, quota_block, limit_reached
data.handoff.requested_atrequired	string	format date-time
data.handoff.requested_byrequired	"shopper" \| "ai" \| "agent" \| "system"
data.handoff.shopperrequired	HandoffShopper	`HandoffAdmin.shopper` (`platform_customer_id` only for `identity_level = customer`).
data.handoff.shopper.emailrequired	string \| null
data.handoff.shopper.email_verifiedrequired	boolean
data.handoff.shopper.identity_levelrequired	"guest" \| "order_lookup" \| "order_otp" \| "customer"
data.handoff.shopper.namerequired	string \| null
data.handoff.shopper.platform_customer_idrequired	string \| null
data.handoff.staterequired	"requested" \| "waiting_for_agent" \| "live" \| "delivered_offline" \| "failed" \| "resolved"
data.handoff.statusrequired	string (enum)	one of requested, waiting_for_agent, live, delivering, delivered, failed, resolved, cancelled
data.handoff.summaryrequired	string \| null
data.handoff.targetrequired	"live_chat" \| "email" \| "helpdesk" \| null
data.handoff.targetsrequired	HandoffTargetView[]
data.handoff.targets[].external_urlrequired	string \| null	format uri · ≤ 2048 characters
data.handoff.targets[].integration_idrequired	string \| null	pattern `^int_[0-9a-hjkmnp-tv-z]{26}$`
data.handoff.targets[].last_errorrequired	string \| null
data.handoff.targets[].statusrequired	"pending" \| "delivered" \| "failed" \| "skipped"
data.handoff.targets[].typerequired	string
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"handoff.updated"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "handoff": {
      "agent": null,
      "expected_wait_seconds": 120,
      "id": "hof_01j8000000e008000000000001",
      "message": "We've let the team know. Someone will be with you shortly.",
      "state": "waiting_for_agent",
      "target": "live_chat"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "handoff.updated"
}

`lead.captured`

A shopper left contact details in the chat.

Sent with ShopAssist-Event-Type: lead.captured. Acknowledge with any 2xx within 10 seconds.

Payload of lead.captured
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	LeadEventData	`{ lead: Lead }`.
data.leadrequired	Lead	`Lead` (03 §6.19).
data.lead.confirmed_atrequired	string \| null	format date-time
data.lead.consentsrequired	ConsentRecordView[]
data.lead.consents[].confirmed_atrequired	string \| null	format date-time
data.lead.consents[].consent_textrequired	string
data.lead.consents[].consent_text_versionrequired	string
data.lead.consents[].created_atrequired	string	format date-time
data.lead.consents[].idrequired	string	pattern `^cns_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.consents[].is_grantedrequired	boolean
data.lead.consents[].localerequired	string
data.lead.consents[].purposerequired	string (enum)	one of newsletter, marketing_email, back_in_stock, transcript_email, handoff_share, analytics, preferences
data.lead.consents[].sourcerequired	string (enum)	one of widget_form, chat, cmp, double_opt_in, unsubscribe, dashboard, api
data.lead.consents[].withdrawn_atrequired	string \| null	format date-time
data.lead.conversation_idrequired	string \| null	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.created_atrequired	string	format date-time
data.lead.emailrequired	string
data.lead.idrequired	string	pattern `^lead_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.localerequired	string \| null
data.lead.namerequired	string \| null
data.lead.newsletter_statusrequired	"none" \| "pending_confirmation" \| "confirmed" \| "unsubscribed"
data.lead.platform_sync_statusrequired	"not_required" \| "pending" \| "synced" \| "failed"
data.lead.purposesrequired	("newsletter" \| "contact_request" \| "back_in_stock" \| "transcript")[]
data.lead.sourcerequired	"lead_form" \| "chat_tool" \| "handoff" \| "back_in_stock"
data.lead.unsubscribed_atrequired	string \| null	format date-time
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"lead.captured"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "lead": {
      "confirmed_at": "2026-09-28T10:15:30.123Z",
      "consents": [
        {
          "confirmed_at": "2026-09-28T10:15:30.123Z",
          "consent_text": "string",
          "consent_text_version": "string",
          "created_at": "2026-09-28T10:15:30.123Z",
          "id": "cns_01j8000000e008000000000000",
          "is_granted": true,
          "locale": "da-DK",
          "purpose": "newsletter",
          "source": "widget_form",
          "withdrawn_at": "2026-09-28T10:15:30.123Z"
        }
      ],
      "conversation_id": "conv_01j8000000e008000000000000",
      "created_at": "2026-09-28T10:15:30.123Z",
      "email": "string",
      "id": "lead_01j8000000e008000000000000",
      "locale": "da-DK",
      "name": "string",
      "newsletter_status": "none",
      "platform_sync_status": "not_required",
      "purposes": [
        "newsletter"
      ],
      "source": "lead_form",
      "unsubscribed_at": "2026-09-28T10:15:30.123Z"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "lead.captured"
}

`lead.confirmed`

A shopper confirmed their newsletter sign-up (double opt-in).

Sent with ShopAssist-Event-Type: lead.confirmed. Acknowledge with any 2xx within 10 seconds.

Payload of lead.confirmed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	LeadEventData	`{ lead: Lead }`.
data.leadrequired	Lead	`Lead` (03 §6.19).
data.lead.confirmed_atrequired	string \| null	format date-time
data.lead.consentsrequired	ConsentRecordView[]
data.lead.consents[].confirmed_atrequired	string \| null	format date-time
data.lead.consents[].consent_textrequired	string
data.lead.consents[].consent_text_versionrequired	string
data.lead.consents[].created_atrequired	string	format date-time
data.lead.consents[].idrequired	string	pattern `^cns_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.consents[].is_grantedrequired	boolean
data.lead.consents[].localerequired	string
data.lead.consents[].purposerequired	string (enum)	one of newsletter, marketing_email, back_in_stock, transcript_email, handoff_share, analytics, preferences
data.lead.consents[].sourcerequired	string (enum)	one of widget_form, chat, cmp, double_opt_in, unsubscribe, dashboard, api
data.lead.consents[].withdrawn_atrequired	string \| null	format date-time
data.lead.conversation_idrequired	string \| null	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.created_atrequired	string	format date-time
data.lead.emailrequired	string
data.lead.idrequired	string	pattern `^lead_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.localerequired	string \| null
data.lead.namerequired	string \| null
data.lead.newsletter_statusrequired	"none" \| "pending_confirmation" \| "confirmed" \| "unsubscribed"
data.lead.platform_sync_statusrequired	"not_required" \| "pending" \| "synced" \| "failed"
data.lead.purposesrequired	("newsletter" \| "contact_request" \| "back_in_stock" \| "transcript")[]
data.lead.sourcerequired	"lead_form" \| "chat_tool" \| "handoff" \| "back_in_stock"
data.lead.unsubscribed_atrequired	string \| null	format date-time
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"lead.confirmed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "lead": {
      "confirmed_at": "2026-09-28T10:15:30.123Z",
      "consents": [
        {
          "confirmed_at": "2026-09-28T10:15:30.123Z",
          "consent_text": "string",
          "consent_text_version": "string",
          "created_at": "2026-09-28T10:15:30.123Z",
          "id": "cns_01j8000000e008000000000000",
          "is_granted": true,
          "locale": "da-DK",
          "purpose": "newsletter",
          "source": "widget_form",
          "withdrawn_at": "2026-09-28T10:15:30.123Z"
        }
      ],
      "conversation_id": "conv_01j8000000e008000000000000",
      "created_at": "2026-09-28T10:15:30.123Z",
      "email": "string",
      "id": "lead_01j8000000e008000000000000",
      "locale": "da-DK",
      "name": "string",
      "newsletter_status": "none",
      "platform_sync_status": "not_required",
      "purposes": [
        "newsletter"
      ],
      "source": "lead_form",
      "unsubscribed_at": "2026-09-28T10:15:30.123Z"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "lead.confirmed"
}

`lead.unsubscribed`

A shopper unsubscribed.

Sent with ShopAssist-Event-Type: lead.unsubscribed. Acknowledge with any 2xx within 10 seconds.

Payload of lead.unsubscribed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	LeadEventData	`{ lead: Lead }`.
data.leadrequired	Lead	`Lead` (03 §6.19).
data.lead.confirmed_atrequired	string \| null	format date-time
data.lead.consentsrequired	ConsentRecordView[]
data.lead.consents[].confirmed_atrequired	string \| null	format date-time
data.lead.consents[].consent_textrequired	string
data.lead.consents[].consent_text_versionrequired	string
data.lead.consents[].created_atrequired	string	format date-time
data.lead.consents[].idrequired	string	pattern `^cns_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.consents[].is_grantedrequired	boolean
data.lead.consents[].localerequired	string
data.lead.consents[].purposerequired	string (enum)	one of newsletter, marketing_email, back_in_stock, transcript_email, handoff_share, analytics, preferences
data.lead.consents[].sourcerequired	string (enum)	one of widget_form, chat, cmp, double_opt_in, unsubscribe, dashboard, api
data.lead.consents[].withdrawn_atrequired	string \| null	format date-time
data.lead.conversation_idrequired	string \| null	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.created_atrequired	string	format date-time
data.lead.emailrequired	string
data.lead.idrequired	string	pattern `^lead_[0-9a-hjkmnp-tv-z]{26}$`
data.lead.localerequired	string \| null
data.lead.namerequired	string \| null
data.lead.newsletter_statusrequired	"none" \| "pending_confirmation" \| "confirmed" \| "unsubscribed"
data.lead.platform_sync_statusrequired	"not_required" \| "pending" \| "synced" \| "failed"
data.lead.purposesrequired	("newsletter" \| "contact_request" \| "back_in_stock" \| "transcript")[]
data.lead.sourcerequired	"lead_form" \| "chat_tool" \| "handoff" \| "back_in_stock"
data.lead.unsubscribed_atrequired	string \| null	format date-time
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"lead.unsubscribed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "lead": {
      "confirmed_at": "2026-09-28T10:15:30.123Z",
      "consents": [
        {
          "confirmed_at": "2026-09-28T10:15:30.123Z",
          "consent_text": "string",
          "consent_text_version": "string",
          "created_at": "2026-09-28T10:15:30.123Z",
          "id": "cns_01j8000000e008000000000000",
          "is_granted": true,
          "locale": "da-DK",
          "purpose": "newsletter",
          "source": "widget_form",
          "withdrawn_at": "2026-09-28T10:15:30.123Z"
        }
      ],
      "conversation_id": "conv_01j8000000e008000000000000",
      "created_at": "2026-09-28T10:15:30.123Z",
      "email": "string",
      "id": "lead_01j8000000e008000000000000",
      "locale": "da-DK",
      "name": "string",
      "newsletter_status": "none",
      "platform_sync_status": "not_required",
      "purposes": [
        "newsletter"
      ],
      "source": "lead_form",
      "unsubscribed_at": "2026-09-28T10:15:30.123Z"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "lead.unsubscribed"
}

`message.created`

A message was added to a conversation. Opt-in and high volume.

Sent with ShopAssist-Event-Type: message.created. Acknowledge with any 2xx within 10 seconds.

Payload of message.created
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	MessageCreatedData	`{ conversation_id; message: ApiMessage }` (opt-in, high volume).
data.conversation_idrequired	string	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.messagerequired	ApiMessage	`{ id; seq; role; text; blocks; is_ai_generated; author: {type; display_name}; created_at }`.
data.message.authorrequired	MessageAuthor	Who wrote a message.
data.message.author.display_namerequired	string \| null
data.message.author.typerequired	"shopper" \| "ai" \| "human" \| "system"
data.message.blocksrequired	UiBlock[]
data.message.created_atrequired	string	format date-time
data.message.idrequired	string	pattern `^msg_[0-9a-hjkmnp-tv-z]{26}$`
data.message.is_ai_generatedrequired	boolean
data.message.rolerequired	"shopper" \| "assistant" \| "agent" \| "system"
data.message.seqrequired	integer	≥ 0
data.message.textrequired	string
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"message.created"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "conversation_id": "conv_01j8000000e008000000000000",
    "message": {
      "author": {
        "display_name": "string",
        "type": "shopper"
      },
      "blocks": [
        {
          "as_of": "2026-09-28T10:15:30.123Z",
          "id": "b1",
          "items": [
            {
              "actions": {
                "add_to_cart": true,
                "check_store_stock": true,
                "notify_back_in_stock": false
              },
              "as_of": "2026-09-28T10:15:30.123Z",
              "availability": {
                "as_of": "2026-09-28T10:15:30.123Z",
                "label": "Only 2 left",
                "quantity": 2,
                "status": "low_stock"
              },
              "badges": [
                "New"
              ],
              "default_variant_id": "var_01j8000000e008000000000001",
              "image": {
                "alt": "City bike",
                "height": 600,
                "url": "https://cdn.shopify.com/s/files/1/demo/bike-1.jpg",
                "width": 800
              },
              "options": [
                {
                  "name": "Size",
                  "values": [
                    {
                      "is_available": true,
                      "value": "M"
                    },
                    {
                      "is_available": false,
                      "value": "L"
                    }
                  ]
                }
              ],
              "price": {
                "amount": "4999",
                "currency": "DKK",
                "display": "4.999,00 kr."
              },
              "product_id": "prd_01j8000000e008000000000001",
              "rating": {
                "average": 4.6,
                "count": 128
              },
              "subtitle": "Nordic Bikes",
              "title": "Nordic City Bike 7-speed",
              "url": "https://nordicbikes.example/products/city-bike?utm_source=shopassist&utm_medium=chat",
              "variants": [
                {
                  "availability": {
                    "as_of": "2026-09-28T10:15:30.123Z",
                    "label": "Only 2 left",
                    "quantity": 2,
                    "status": "low_stock"
                  },
                  "cart_ref": {
                    "variant_gid": "gid://shopify/ProductVariant/4711"
                  },
                  "options": {
                    "Size": "M"
                  },
                  "price": {
                    "amount": "4999",
                    "currency": "DKK",
                    "display": "4.999,00 kr."
                  },
                  "title": "M",
                  "variant_id": "var_01j8000000e008000000000001"
                }
              ]
            }
          ],
          "layout": "carousel",
          "title": "City bikes in stock",
          "type": "products"
        }
      ],
      "created_at": "2026-09-28T10:15:30.123Z",
      "id": "msg_01j8000000e008000000000000",
      "is_ai_generated": true,
      "role": "shopper",
      "seq": 0,
      "text": "string"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "message.created"
}

`order.attributed`

An order was attributed to a conversation.

Sent with ShopAssist-Event-Type: order.attributed. Acknowledge with any 2xx within 10 seconds.

Payload of order.attributed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	OrderAttributedData	`{ order }`.
data.orderrequired	AttributedOrderEventView	`{ id; platform_order_id; order_number; attribution_type; total; assisted_amount; ordered_at; conversation_id }`.
data.order.assisted_amountrequired	Money \| null
data.order.assisted_amount.amountrequired	string	pattern `^-?\d+(\.\d{1,6})?$`
data.order.assisted_amount.currencyrequired	string	pattern `^[A-Z]{3}$`
data.order.attribution_typerequired	"bot_add_to_cart" \| "bot_checkout_link" \| "assisted_session"
data.order.conversation_idrequired	string \| null	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data.order.idrequired	string	pattern `^aor_[0-9a-hjkmnp-tv-z]{26}$`
data.order.order_numberrequired	string \| null
data.order.ordered_atrequired	string	format date-time
data.order.platform_order_idrequired	string
data.order.totalrequired	Money	An amount with its currency (`03` §2.4 `Money`).
data.order.total.amountrequired	string	pattern `^-?\d+(\.\d{1,6})?$`
data.order.total.currencyrequired	string	pattern `^[A-Z]{3}$`
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"order.attributed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "order": {
      "assisted_amount": {
        "amount": "499.95",
        "currency": "DKK"
      },
      "attribution_type": "bot_add_to_cart",
      "conversation_id": "conv_01j8000000e008000000000000",
      "id": "aor_01j8000000e008000000000000",
      "order_number": "string",
      "ordered_at": "2026-09-28T10:15:30.123Z",
      "platform_order_id": "string",
      "total": {
        "amount": "499.95",
        "currency": "DKK"
      }
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "order.attributed"
}

`privacy_request.completed`

A privacy request (export or erasure) finished.

Sent with ShopAssist-Event-Type: privacy_request.completed. Acknowledge with any 2xx within 10 seconds.

Payload of privacy_request.completed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	PrivacyRequestCompletedData	`{ privacy_request: PrivacyRequest }`.
data.privacy_requestrequired	PrivacyRequest	`PrivacyRequest` (03 §6.16).
data.privacy_request.completed_atrequired	string \| null	format date-time
data.privacy_request.created_atrequired	string	format date-time
data.privacy_request.due_atrequired	string	format date-time
data.privacy_request.idrequired	string	pattern `^prq_[0-9a-hjkmnp-tv-z]{26}$`
data.privacy_request.sourcerequired	string (enum)	one of dashboard, merchant_api, shopify_customers_data_request, shopify_customers_redact, shopify_shop_redact, woocommerce, prestashop, magento2, operator
data.privacy_request.statsrequired	object
data.privacy_request.statusrequired	"received" \| "processing" \| "completed" \| "failed" \| "cancelled"
data.privacy_request.subject_summaryrequired	string	Masked, e.g. "email j***@example.com", "customer 4711"
data.privacy_request.typerequired	"export" \| "delete"
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"privacy_request.completed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "privacy_request": {
      "completed_at": "2026-09-28T10:15:30.123Z",
      "created_at": "2026-09-28T10:15:30.123Z",
      "due_at": "2026-09-28T10:15:30.123Z",
      "id": "prq_01j8000000e008000000000000",
      "source": "dashboard",
      "stats": {},
      "status": "received",
      "subject_summary": "string",
      "type": "export"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "privacy_request.completed"
}

`store.status_changed`

A store changed status (for example connected, disconnected, suspended).

Sent with ShopAssist-Event-Type: store.status_changed. Acknowledge with any 2xx within 10 seconds.

Payload of store.status_changed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	StoreStatusChangedData	`{ store: StorePublic; previous_status }`.
data.previous_statusrequired	string (enum)	one of pending_connect, connecting, syncing, active, paused, reconnect_required, disconnected, uninstalled, suspended
data.storerequired	StorePublic	`{ id; name; platform; status; primary_domain; catalog_locale; currency; timezone; capabilities; created_at }`.
data.store.capabilitiesrequired	object	stores.capabilities (02 §17)
data.store.catalog_localerequired	string	2–35 characters · pattern `^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$`
data.store.created_atrequired	string	format date-time
data.store.currencyrequired	string	pattern `^[A-Z]{3}$`
data.store.idrequired	string	pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
data.store.namerequired	string
data.store.platformrequired	"shopify" \| "magento2" \| "woocommerce" \| "prestashop" \| "generic"
data.store.primary_domainrequired	string \| null
data.store.statusrequired	string (enum)	one of pending_connect, connecting, syncing, active, paused, reconnect_required, disconnected, uninstalled, suspended
data.store.timezonerequired	string
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"store.status_changed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "previous_status": "pending_connect",
    "store": {
      "capabilities": {},
      "catalog_locale": "da-DK",
      "created_at": "2026-09-28T10:15:30.123Z",
      "currency": "DKK",
      "id": "sto_01j8000000e008000000000000",
      "name": "string",
      "platform": "shopify",
      "primary_domain": "string",
      "status": "pending_connect",
      "timezone": "string"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "store.status_changed"
}

`sync.failed`

A catalog sync run failed.

Sent with ShopAssist-Event-Type: sync.failed. Acknowledge with any 2xx within 10 seconds.

Payload of sync.failed
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	SyncFailedData	`{ sync_run: SyncRun }` (topic `sync.run_failed`).
data.sync_runrequired	SyncRun	`SyncRun` (03 §6.9).
data.sync_run.created_atrequired	string	format date-time
data.sync_run.error_coderequired	string \| null
data.sync_run.error_detailrequired	string \| null	Merchant-safe message
data.sync_run.finished_atrequired	string \| null	format date-time
data.sync_run.idrequired	string	pattern `^sync_[0-9a-hjkmnp-tv-z]{26}$`
data.sync_run.kindrequired	string (enum)	one of initial, incremental, reconcile, content, translations, inventory, locations, single, feed
data.sync_run.progressrequired	object	{phase, done, total}
data.sync_run.started_atrequired	string \| null	format date-time
data.sync_run.statsrequired	object
data.sync_run.statusrequired	"queued" \| "running" \| "succeeded" \| "partial" \| "failed" \| "cancelled"
data.sync_run.triggerrequired	string (enum)	one of install, webhook, push, ping, schedule, manual, operator
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"sync.failed"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "sync_run": {
      "created_at": "2026-09-28T10:15:30.123Z",
      "error_code": "string",
      "error_detail": "string",
      "finished_at": "2026-09-28T10:15:30.123Z",
      "id": "sync_01j8000000e008000000000000",
      "kind": "initial",
      "progress": {},
      "started_at": "2026-09-28T10:15:30.123Z",
      "stats": {},
      "status": "queued",
      "trigger": "install"
    }
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "sync.failed"
}

`usage.threshold_reached`

Usage reached 80 % or 100 % of the included conversations, or the overage budget.

Sent with ShopAssist-Event-Type: usage.threshold_reached. Acknowledge with any 2xx within 10 seconds.

Payload of usage.threshold_reached
Field	Type	Description
api_versionrequired	"v1"	default "v1"
created_atrequired	string	format date-time
datarequired	UsageThresholdReachedData	`{ billing_account_id; threshold; units_total; included_units }` (mapping from the internal thresholds: 01 §8.1).
data.billing_account_idrequired	string	pattern `^bac_[0-9a-hjkmnp-tv-z]{26}$`
data.included_unitsrequired	integer \| null	≥ 0
data.thresholdrequired	"80_percent" \| "100_percent" \| "budget_reached"
data.units_totalrequired	integer	≥ 0
idrequired	string	pattern `^evt_[0-9a-hjkmnp-tv-z]{26}$`
organization_idrequired	string	pattern `^org_[0-9a-hjkmnp-tv-z]{26}$`
store_idrequired	string \| null	null for organization-level events (usage)pattern `^sto_[0-9a-hjkmnp-tv-z]{26}$`
typerequired	"usage.threshold_reached"

{
  "api_version": "v1",
  "created_at": "2026-09-28T10:15:30.123Z",
  "data": {
    "billing_account_id": "bac_01j8000000e008000000000000",
    "included_units": 0,
    "threshold": "80_percent",
    "units_total": 0
  },
  "id": "evt_01j8000000e008000000000000",
  "organization_id": "org_01j8000000e008000000000000",
  "store_id": "sto_01j8000000e008000000000000",
  "type": "usage.threshold_reached"
}

Webhook events

action.executedCopy Anchor Link

back_in_stock.notifiedCopy Anchor Link

back_in_stock.subscribedCopy Anchor Link

conversation.closedCopy Anchor Link

conversation.createdCopy Anchor Link

csat.submittedCopy Anchor Link

handoff.requestedCopy Anchor Link

handoff.updatedCopy Anchor Link

lead.capturedCopy Anchor Link

lead.confirmedCopy Anchor Link

lead.unsubscribedCopy Anchor Link

message.createdCopy Anchor Link

order.attributedCopy Anchor Link

privacy_request.completedCopy Anchor Link

store.status_changedCopy Anchor Link

sync.failedCopy Anchor Link

usage.threshold_reachedCopy Anchor Link

On this page