Webhooks and your own identifier

XUND can notify your server when a check in the Symptom & Illness Check App finishes. Setup, events, signature verification, and retries are described in the API Webhooks guide. This page covers how to get your own identifier back in the notification as data.state. state is a UUID you generate and map, on your server, to whatever the check belongs to — for example a session or a user — so you can link the finished check to it. Don't use a session token itself: state travels in URLs and in the page.

The examples on this page use await; run them inside an async function or a <script type="module">.

How state reaches the webhook

1. Your server signs the auth code with your identifier. When you create the auth code, use your identifier as state and add scope=state (returnStateInWebhook: true in the snippets). state must be a UUID.

2. Pass the same value to the embed.

   <script … auth-code="AUTH-CODE-FROM-YOUR-SERVER" state="YOUR-IDENTIFIER-UUID"></script>

   const xundApp = await XUND.scic.init({
     clientId: 'YOUR-CLIENT-ID',
     webappCode: 'YOUR-WEBAPP-CODE',
     authCode: 'AUTH-CODE-FROM-YOUR-SERVER',
     state: 'YOUR-IDENTIFIER-UUID',
     targetContainerId: 'xund-container',
   })

   With the JS API, state is a top-level property, not part of customization.

3. The webhook carries it as data.state when the check finishes:

   {
     "type": "check.finished.report",
     "timestamp": "2026-09-29T14:32:00.000Z",
     "data": {
       "checkId": "5e63f95e-ef3b-42ce-9027-ff6e021e19ef",
       "state": "8b0e6c1a-1f7d-4c2e-9a53-2d6f0e7b4a91"
     }
   }

Common mistakes

• Signing with a random UUID and passing your identifier only to the embed. The value in the webhook comes from the auth code, so you get the random UUID back.
• Forgetting scope=state. The auth code then carries no state, and the webhook has no data.state.
• An identifier that is not a UUID. Your server's /authorize call is rejected with status 400, so no auth code is created.
• Different values on the server and in the embed. Pass exactly the value your server signed.