Configuring Webhook Listeners

This guide details the steps to set up webhook integration with your service. It lists the API calls required to set up a Webhook Listener and its Subscriptions. See Webhooks for the notification envelope and payload structure, signature verification, delivery guarantees, and the full list of available topics.

Vocabulary

• Webhook Topic - a specific, named category used to organize and send notifications to subscribers.
• Webhook Listener - receives notifications for subscribed topics.
• Webhook Topic Subscription - subscribes listener to a particular topic. Webhook listener can have multiple subscriptions. Webhook Listener without subscriptions does not receive notifications.

How It Works

You will need to implement a webhook listener and register its url with Immersve. Only HTTPS protocol is supported.

Immersve will send notifications to the listener for any topics it is subscribed to. Notifications are sent to the Webhook Listener url as HTTP POST requests with the notification topic as a path parameter. See Webhooks for the full notification protocol, including how the topic name is appended to your listener's url to form the delivery path.

Registering Webhook Listeners

You must first register your Webhook Listener before it can subscribe to a topic. To register a Webhook Listener, call Create Webhook Listener with your partner account id and your base url.

curl -L "https://${imsv_api_host}/api/webhook-listeners" \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: ${account_admin_api_key}" \
  -H "X-Api-Secret: ${account_admin_api_secret}" \
  -d '{
    "accountId": "'${partner_account_id}'",
    "url": "https://example.com/webhooks"
  }'

Subscribing to Topics

In order to receive notifications, your Webhook Listener must have a subscription for the desired topics. Use the Webhook Topic Subscription endpoint to subscribe your Webhook Listener to topics.

curl -L 'https://${imsv_api_host}/api/webhook-listeners/${listenerId}/subscribe' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: ${account_admin_api_key}" \
  -H "X-Api-Secret: ${account_admin_api_secret}" \
  -d '{
    "topic": "kyc-succeeded"
  }'

Once topic subscriptions have been created, your Webhook Listener will be ready to receive notifications for the subscribed topics.

Testing Webhooks

Webhook setup can be tested by calling the Send Webhook Test Notification endpoint. You can use any of the available Topics documented on our Webhook Topics reference. This will fire a delivery of the notification with the example payload for the requested Topic to all subscribed Webhook Listeners. Test notification delivery can be targeted to a specific listener id using the listenerId body parameter.

curl -L 'https://api.immersve.com/api/webhook-test-notifications' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: ${account_admin_api_key}" \
  -H "X-Api-Secret: ${account_admin_api_secret}" \
  -d '{
    "topic": "kyc-succeeded",
    "accountId": "'${partner_account_id}'",
  }'

Debugging Webhooks

If a notification doesn't arrive as expected, use the List Webhook Notifications endpoint to inspect delivery history for your account. Each entry reports the current deliveryStatus and, under lastDelivery, the outcome of the most recent attempt — including the response your listener returned.

curl -L -X GET "https://${imsv_api_host}/api/accounts/${partner_account_id}/webhook-notifications" \
  -H "X-Api-Key: ${account_admin_api_key}" \
  -H "X-Api-Secret: ${account_admin_api_secret}"

deliveryStatus tells you whether a notification is still retrying (pending, attempting), succeeded (delivered), or gave up (aborted, failed) — see Webhooks for the full delivery guarantees. The example below shows a notification whose most recent attempt failed with a 500 response; requestBody under lastDelivery (omitted here) carries the exact envelope that was sent, following the same shape described in that guide's Envelope section.

{
  "id": "dcd07ae53c03209282543316312e4c38",
  "topic": "kyc-succeeded",
  "attempts": 3,
  "createdAt": "2026-08-17T01:46:14.481Z",
  "modifiedAt": "2026-08-17T01:52:31.204Z",
  "deliveryStatus": "failed",
  "lastDelivery": {
    "requestUrl": "https://example.com/webhooks/kyc-succeeded",
    "requestTimestamp": "2026-08-17T01:52:30.990Z",
    "responseStatus": 500,
    "responseTimestamp": "2026-08-17T01:52:31.204Z",
    "duration": 214
  }
}