12. Webhooks

How the platform delivers signed event notifications: delivery semantics, HMAC signing, payload structure, and event types.

12.1 Overview

Webhooks are the platform's asynchronous outbound channel — HTTP notifications sent from the Identity Platform to integrator-configured endpoints when business events occur. They are fired asynchronously after the event completes — they do not block the API response. Webhooks are never on the device decision path — a device at a gate cannot block on an async webhook; that path uses the synchronous broker (§10).

Conditional delivery: Webhook delivery only occurs if the tenant has at least one active endpoint subscribed to the specific event type. If no matching endpoint exists, no delivery is attempted. Audit logging always occurs regardless of webhook configuration.

The webhook_endpoints schema (URL, event subscriptions, status, scope, signing-secret hash) is in §5.3.

12.2 Delivery

Property	Value
Method	HTTP POST
Content-Type	application/json
Timeout	5 seconds
Retry	3 attempts with exponential backoff (1 min, 5 min, 15 min)
Failure	After 3 consecutive failures, delivery is marked as failed and an audit event is logged
Acknowledgment	Integrator must return HTTP 2xx within the timeout

Webhooks are sent directly via HTTP POST with retries on failure. There is no intermediate queue — the platform sends the request, and if the endpoint doesn't respond with 2xx within the timeout, it retries with exponential backoff.

12.3 Security & Signing Secrets

Each webhook endpoint has its own signing secret, separate from OAuth client secrets, with an independent lifecycle:

1. Tenant Admin creates a webhook endpoint via Web Console (or the webhook management API — §14.1)
2. Platform generates a signing secret (random 256-bit, base64url-encoded)
3. Plaintext secret is returned once — the server stores only the bcrypt hash
4. Tenant Admin copies the secret to their backend for webhook signature verification
5. If lost, the admin regenerates — the old secret is invalidated immediately

Why separate from client secrets? Webhook endpoints and OAuth clients have independent lifecycles. A tenant may have multiple webhook endpoints pointing to different services, and multiple OAuth clients for different backends. Rotating a client secret should not break webhook verification, and vice versa.

Signed request headers:

Header	Value
X-Link-Signature	sha256=<hex> — HMAC-SHA256 of the raw request body using the endpoint's signing secret
X-Link-Event	Event type (e.g., kyc.verified)
X-Link-Delivery	Unique delivery ID (for deduplication)

All webhook requests are sent over TLS. Integrators must verify the X-Link-Signature header before processing the payload: compute HMAC-SHA256(raw_body, signing_secret) and compare it to the header value.

12.4 Payload Structure

All webhook events use a standard envelope:

{
  "event_id": "evt_abc123",
  "event_type": "verification.complete",
  "tenant_id": "link-wallet",
  "timestamp": "2026-03-30T10:00:00Z",
  "data": {
    "user_id": "user_123",
    "challenge_id": "ch_abc",
    "confidence": 0.9997,
    "metadata": {
      "document_id": "doc_123",
      "document_hash": "sha256:..."
    }
  }
}

Passthrough metadata: The metadata field in data echoes back whatever the integrator included in the original API request. For example, if the integrator passed {document_id, document_hash} when creating a verification challenge, those same fields appear in the verification.complete webhook. This allows the integrator to correlate webhook events with their business context without maintaining a separate mapping.

12.5 Event Types

All webhook event types — grouped Users / KYC / Biometric / Consent / Platform — are cataloged in §16 (Event Reference), which maps each business event to its audit-event name and its webhook-event name in one table. Platform-scoped events (platform.*, e.g. cert expiry) are delivered only to scope='platform' endpoints (§12.6).

12.6 Configuration

Tenant Admins configure webhook endpoints via the Web Console (Settings → Webhooks) or the webhook management API.

• Multiple endpoints per tenant — different URLs can receive different events (e.g., one endpoint for KYC events, another for biometric events)
• Per-endpoint event subscription — select which events each endpoint receives (grouped by Users, KYC, Biometric, Consent)
• Active/inactive toggle — temporarily disable an endpoint without deleting it
• Signing secret per endpoint — auto-generated, shown once (see §12.3)
• Scope — tenant (default; receives events for that tenant's users) or platform (Platform Admin only; receives platform.* events like cert expiry across the deployment). Platform-scoped endpoints are not visible to tenant admins.

12.7 Webhook Management API

Webhook endpoints are managed via the Console API. See Section 14.1 for the complete endpoint reference (create, list, update, delete, regenerate signing secret).