Webhooks

Alianza publishes events about platform activity, and you subscribe to the ones you care about. When something changes — a new Experience Connection, an assignment, a user added or removed in an account you serve — the event is delivered to your system.

You subscribe to events; a webhook is how those events are delivered. That distinction matters for what comes later: webhooks are currently the only delivery mechanism, and other transports have been discussed. Your subscription describes which events you want, not that you want webhooks — so read "subscription" throughout as an event subscription that happens to be delivered over HTTPS today.

Delivery follows standard webhook design patterns: automatic retries and idempotency via a server-generated webhook-id.

Subscribe to events to keep your system in sync without polling. End users can change Experience Connections and Assignments from an Alianza portal, and events are what relay those changes to you.

In this guide

Prerequisites

  • The experienceId Alianza issued for your Experience.
  • A publicly accessible HTTPS endpoint that accepts POST requests with a JSON body. It must:
    • Be reachable from the internet — not behind a firewall or NAT without port forwarding.
    • Accept requests on the standard HTTPS port (443).
    • Respond within a reasonable timeout — typically 15 seconds.
    • Return a 2xx status code (200, 201, 202, …) to acknowledge receipt.

Optional, but recommended:

  • A development or sandbox environment for testing your webhook integration.
  • Logging infrastructure to track incoming events for debugging and auditing.

Getting started

1. Create your event subscription

Subscriptions are currently created by Alianza on your behalf. Provide the Alianza team:

  • Destination URL — where events are POSTed, e.g. https://your-system.io/webhooks/experiences
  • experienceId — which Experience the event subscription is associated with, if you have more than one
  • Event types — which events you want, from the event catalog

Spec gap. Subscriptions are not modelled in the OpenAPI spec, so the relationship between a subscription and an Experience is undocumented. If you operate more than one Experience it is unclear whether a single subscription can carry several experienceIds, or whether each Experience needs its own subscription with its own destination URL. Confirm with your Alianza contact before designing around either shape.

Gap ID subscription-experience-cardinality

For example:

{
  "destinationUrl": "https://your-system.io/webhooks/experiences",
  "types": [
    "experience.connection.created",
    "experience.connection.activated",
    "experience.connection.deactivated",
    "experience.connection.deleted",
    "experience.assignment.created",
    "experience.assignment.deleted",
    "provisioning.user.created",
    "provisioning.user.deleted"
  ]
}

Alianza registers your endpoint and enables delivery. You receive confirmation along with a unique subscriptionId, which identifies your subscription for future reference and updates, and which appears in every event payload.

Spec gap. A self-service subscription API is planned but not yet available; Alianza manages subscriptions for Experience Providers in the interim. The registration interface may change when the subscription service ships.

Gap ID webhook-subscription-api

2. Implement your endpoint

Create a POST endpoint at the registered URL. Every event arrives as JSON with a common envelope; the type and data fields vary by event.

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

Each request also carries webhook-id and webhook-timestamp headers. See the event reference for the full envelope and per-event data schemas.

3. Verify and respond

Test your endpoint with a sample payload:

curl -X POST https://your-system.io/webhooks/experiences \
  -H "Content-Type: application/json" \
  -H "webhook-id: 50696697-a2e6-4357-9f81-9e59b4f54004" \
  -H "webhook-timestamp: 1783452103" \
  -d '{
    "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"
    }
  }'

Parse the event, process it, and return 200 OK. Any 2xx response signals success; anything else triggers retries.

What's next