Webhook event reference

All webhook events are delivered as POST requests to your registered endpoint with a structured JSON payload. The data object carries event-specific fields; the wrapper provides consistent metadata for subscription routing and event tracking.

Request structure

POST https://your-system.io/webhooks/experiences HTTP/1.1
Content-Type: application/json
webhook-id: fc2e2874-a588-45a5-9853-b36bb88f76a8
webhook-timestamp: 1783452103

{
  "type": "experience.connection.created",
  "timestamp": "2026-07-10T14:32:18Z",
  "subscriptionId": "d9792eb7-56fb-4cfa-b303-8ce1b1f0b4b7",
  "scope": {
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b"
  },
  "data": {}
}

Request headers

Header	Description
`webhook-id`	Unique identifier for this webhook event. Use it to deduplicate identical events.
`webhook-timestamp`	Unix timestamp (seconds) of when the event was sent.

Payload fields

Field	Description
`type`	The type of event, following the `{domain}.{entity}.{action}` naming convention — e.g. `experience.connection.created`.
`timestamp`	ISO 8601 timestamp of when the event occurred, always UTC.
`subscriptionId`	The ID of your event subscription, issued when Alianza creates it.
`scope`	Contains the `experienceId` of the Experience associated with this event.
`data`	Event-specific payload (schemas below).

Event catalog

Events are delivered in real time as the platform processes changes — whether those changes originate from your own API calls, from the Alianza End User Portal, or from system updates.

Every event's data object carries an updatedAt timestamp for the underlying resource. Compare it against what you have stored before applying a change: delivery is not ordered, so an event can arrive after a later state has already been recorded. Discard an event whose updatedAt is older than your stored value rather than letting it overwrite newer data. The same field drives desynchronization recovery.

Experience Connection events

Event	When it fires
`experience.connection.created`	An Experience Connection is created for an account. Fires only when you perform Step 1 of Connect and activate.
`experience.connection.activated`	A connection's state is set to `ACTIVE` — either from the Alianza End User Portal or when you perform Step 3 of Connect and activate.
`experience.connection.deactivated`	A connection's state is set to `INACTIVE` — either from the Alianza End User Portal or by the Experience Provider.
`experience.connection.deleted`	An Experience Connection is deleted for an account. Fires when the Experience Provider deletes it, when the end user removes the connection in the Alianza End User Portal, or when a Service Provider deletes the customer account.

After a experience.connection.deleted event, use the assignability endpoint to confirm whether the connection can be re-established.

Payload (data) schema:

{
  "type": "object",
  "required": [
    "connectionId", "experienceId", "experienceName", "providerId",
    "accountId", "updatedAt"
  ],
  "properties": {
    "connectionId":   { "type": "string", "format": "uuid" },
    "experienceId":   { "type": "string", "format": "uuid" },
    "experienceName": { "type": "string" },
    "providerId":     { "type": "string" },
    "accountId":      { "type": "string", "format": "uuid" },
    "updatedAt":      { "type": "string", "format": "date-time" }
  }
}

Example — Experience connected to an account:

{
  "type": "experience.connection.created",
  "timestamp": "2026-07-10T14:32:18Z",
  "subscriptionId": "d9792eb7-56fb-4cfa-b303-8ce1b1f0b4b7",
  "scope": {
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b"
  },
  "data": {
    "connectionId": "f0cfe99a-5bd6-48ca-9aa9-e13ce7b70c10",
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b",
    "experienceName": "Acme Customer Support IVR",
    "providerId": "prv_acme_experiences",
    "accountId": "f90f4ada-6699-4697-a2da-216f92e61984",
    "updatedAt": "2026-08-06T20:59:08.959211386Z"
  }
}

Experience Assignment events

Event	When it fires
`experience.assignment.created`	Your Experience is assigned to an account — scoped to all users in the account, a telephone number, or an individual user. Your Experience can now be invoked. Fires from the Alianza End User Portal or when you perform Step 2a or 2b of Connect and activate.
`experience.assignment.deleted`	Your Experience is unassigned from an account, user, or telephone number, and is no longer invoked. Fires when the Experience Provider removes the assignment, when it is changed in the Alianza End User Portal, or when an assigned account, user, or telephone number is deleted.

Payload (data) schema:

{
  "type": "object",
  "required": [
    "assignmentId", "experienceId", "experienceName", "providerId",
    "accountId", "targetType", "targetValue", "updatedAt"
  ],
  "properties": {
    "assignmentId":   { "type": "string", "format": "uuid" },
    "experienceId":   { "type": "string", "format": "uuid" },
    "experienceName": { "type": "string" },
    "providerId":     { "type": "string" },
    "accountId":      { "type": "string", "format": "uuid" },
    "targetType":     { "type": "string", "enum": ["USER", "PHONE_NUMBER", "ACCOUNT"] },
    "targetValue":    { "type": "string" },
    "updatedAt":      { "type": "string", "format": "date-time" }
  }
}

targetValue is interpreted according to targetType: a user UUID for USER, an account UUID for ACCOUNT, and an E.164 number for PHONE_NUMBER. See the TargetType reference for per-type format rules.

Example — Experience assigned to a user:

{
  "type": "experience.assignment.created",
  "timestamp": "2026-07-10T14:32:18Z",
  "subscriptionId": "d9792eb7-56fb-4cfa-b303-8ce1b1f0b4b7",
  "scope": {
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b"
  },
  "data": {
    "assignmentId": "9b069450-5939-491a-88fb-27e79cd80054",
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b",
    "experienceName": "Acme Customer Support IVR",
    "providerId": "prv_acme_experiences",
    "accountId": "f90f4ada-6699-4697-a2da-216f92e61984",
    "targetType": "USER",
    "targetValue": "bfbdc8ce-1be8-4bd5-96f4-4dc6351d643f",
    "updatedAt": "2026-08-06T20:59:08.959211386Z"
  }
}

Example — Experience assigned to all users in an account:

{
  "type": "experience.assignment.created",
  "timestamp": "2026-07-10T14:32:18Z",
  "subscriptionId": "d9792eb7-56fb-4cfa-b303-8ce1b1f0b4b7",
  "scope": {
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b"
  },
  "data": {
    "assignmentId": "9b069450-5939-491a-88fb-27e79cd80054",
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b",
    "experienceName": "Acme Customer Support IVR",
    "providerId": "prv_acme_experiences",
    "accountId": "f90f4ada-6699-4697-a2da-216f92e61984",
    "targetType": "ACCOUNT",
    "targetValue": "f90f4ada-6699-4697-a2da-216f92e61984",
    "updatedAt": "2026-08-06T20:59:08.959211386Z"
  }
}

Example — Experience assigned to a telephone number:

{
  "type": "experience.assignment.created",
  "timestamp": "2026-07-10T14:32:18Z",
  "subscriptionId": "d9792eb7-56fb-4cfa-b303-8ce1b1f0b4b7",
  "scope": {
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b"
  },
  "data": {
    "assignmentId": "9b069450-5939-491a-88fb-27e79cd80054",
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b",
    "experienceName": "Acme Customer Support IVR",
    "providerId": "prv_acme_experiences",
    "accountId": "f90f4ada-6699-4697-a2da-216f92e61984",
    "targetType": "PHONE_NUMBER",
    "targetValue": "+18881234567",
    "updatedAt": "2026-08-06T20:59:08.959211386Z"
  }
}

User provisioning events

Event	When it fires
`provisioning.user.created`	A user is created in an account that is assigned to your Experience.
`provisioning.user.deleted`	A user is deleted in an account that is assigned to your Experience.

Payload (data) schema:

{
  "type": "object",
  "required": ["userId", "accountId", "updatedAt"],
  "properties": {
    "userId":    { "type": "string", "format": "uuid" },
    "accountId": { "type": "string", "format": "uuid" },
    "updatedAt": { "type": "string", "format": "date-time" }
  }
}

Example — user created in an account:

{
  "type": "provisioning.user.created",
  "timestamp": "2026-07-10T14:32:18Z",
  "subscriptionId": "d9792eb7-56fb-4cfa-b303-8ce1b1f0b4b7",
  "scope": {
    "experienceId": "65d86040-2d31-4a77-a841-4ba783122c8b"
  },
  "data": {
    "userId": "bfbdc8ce-1be8-4bd5-96f4-4dc6351d643f",
    "accountId": "f90f4ada-6699-4697-a2da-216f92e61984",
    "updatedAt": "2026-08-06T20:59:08.959211386Z"
  }
}

To turn these events into a running seat count, see Tracking user counts.

Spec gap. The webhook events are not yet described in the companion OpenAPI document (the spec declares only an internal example webhook). Schemas on this page are maintained by hand; they will be regenerated when the events land in the spec.

Gap ID webhook-formal-schema

Spec gap. providerId is typed as a plain string with no documented format or length constraint — the examples show an opaque prefixed identifier (prv_acme_experiences) rather than a UUID. Treat it as an opaque string and do not parse it.

Gap ID webhook-provider-id-format