User Connect Webhooks

Tracking2 min read

User Connect webhooks notify your server in real time when one of your users links or unlinks their Kynver identity with your agent. You can use these events to update a "Connected to Kynver" indicator in your app, adjust access levels, or send a confirmation message.

Setting Up a Webhook

Step 1 —

Go to Dashboard → your agent → Settings → User Connect tab.

Step 2 —

Enter your server endpoint URL in the Webhook URL field. The URL must be HTTPS in production. Localhost will not work — the endpoint must be publicly reachable.

Step 3 —

Enter a Webhook Secret (recommended). Kynver will use this to sign requests so you can verify they genuinely came from Kynver.

Step 4 —

Save.

The Payload

Kynver sends a POST request to your URL with Content-Type: application/json.

When a user links their identity:

{
  "event": "user.linked",
  "agentDid": "did:kynver:...",
  "endUserToken": "uuid-...",
  "linkedAt": "2025-01-01T00:00:00Z"
}

When a user unlinks:

{
  "event": "user.unlinked",
  "agentDid": "did:kynver:...",
  "endUserToken": "uuid-..."
}

The endUserToken is the same token returned by getUserConnectInfo() — use it to match the Kynver event to a specific user in your own system.

Verifying the Signature

If you set a Webhook Secret, Kynver includes an X-Kynver-Signature header on every request. Always verify this before processing the event.

import crypto from 'crypto';

function verifyWebhook(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Use rawBody (the raw request body string, not the parsed JSON) and the X-Kynver-Signature header value. Reject any request where the signatures do not match.

Testing Your Webhook

After saving your webhook URL, click "Test webhook" in the dashboard. Kynver sends a sample user.linked payload to your endpoint and shows the HTTP status code your server returned. Use this to confirm your endpoint is working before going live.

Failure Handling & Retries

If your endpoint returns a non-2xx response or times out, Kynver retries the delivery up to 3 times with exponential backoff. After 3 failures, the event is dropped and you receive a notification. To avoid dropped events, make sure your endpoint: - Is publicly reachable (no localhost, no VPN-only addresses) - Responds within 10 seconds - Returns a 2xx status code for successful processing