Webhooks

Receive signed notifications when events occur in DeepCredentials, such as a verification session completing or an invitation reaching a terminal state.

• A publicly accessible HTTPS endpoint to receive webhook events (plain http is accepted only outside production).
• An API credential whose scope matches the resources you fetch (deepcredentials.verify for verification, deepcredentials.issue for issuance, deepcredentials.self-service for self-service).

1. Log in to the DeepCredentials portal.
2. Select your organization and the environment (beta or production) the webhook is for. Each environment has its own webhook URL, signing secret, and event selection.
3. Navigate to B2B API.
4. Enter your Webhook URL (must be HTTPS in production).
5. Click Save.

On first save the portal generates a signing secret — copy it immediately, it is shown only once. Use it to verify webhook signatures (recommended — see Verifying signatures below).

Below the URL the portal renders a checkbox grid grouped by family (Verification / Credential issuance / Self-service). Tick only the events your integration cares about — anything you leave unchecked is silently dropped at our edge with no delivery, no retry.

• New webhook configs default to all events checked, so a first-time setup receives every event type.
• Existing webhook configs keep their current event set when we add new event types — you have to opt in explicitly. In particular, existing integrations must enable credential_invitation.status_changed in the Credential issuance group before invitation callbacks are sent.
• Group-level toggles let you flip an entire family on or off in one click; the header shows All on / Partial / All off for quick scanning.
• Save replaces the full allowlist. There is no separate "subscribe to event X" call.

Once configured, the page can also send a signed sample of any event type to your endpoint (resource IDs are the nil UUID) and shows the response status, the signature, and the exact payload sent. Test deliveries ignore the event selection.

Every webhook event uses the same envelope. data is deliberately slim — only the resource id (and a status hint where the trigger is a status transition). To read claims, captured data, identification details, or any other field, fetch the resource via the linked GET endpoint with your API credential. Webhooks intentionally do not carry captured data or PII over the wire.

The status hint on the *.status_changed and verification.completed events lets you decide which resource to reconcile. credential_status on verification.completed lets you distinguish a suspended or revoked credential from a valid one before the follow-up GET. A failed session carries no reason in the callback; error_code and error_description are on the fetched session. A redeemed invitation includes the resulting offer_id, which is the handoff to the normal offer lifecycle. Self-service event names already encode the lifecycle stage, so they only carry request_id. For swiyu.* events, action repeats the event name without the swiyu. prefix.

Invitation callbacks deliberately omit the invitation code, email address, claims, credential values, custom message, and redemption URL. Creation and code rotation do not emit credential_invitation.status_changed; their synchronous B2B responses are authoritative.

When you need the full payload — claims, a verification session's disclosed attributes, identification result, admin-claims schema, error fields — call the linked GET endpoint with the resource id from data. Same access token (and X-Org-Id / X-Environment headers) you'd use for any B2B call.

Open in API reference →

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/verification-sessions/{sessionId}?response_code=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Open in API reference →

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/credential-offers/{offerId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Open in API reference →

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/credential-invitations/{invitationId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Open in API reference →

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/issued-credentials/{credentialId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Open in API reference →

curl -i -X GET \
  'https://api.dev.deepcredentials.swiss/b2b/v1/self-service/requests/{requestId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Every webhook request includes an HMAC-SHA256 signature of the raw request body in the X-Webhook-Signature header. Verifying it is strongly recommended but is your decision — your endpoint will receive the delivery either way. Skipping verification means you have no way to confirm the request actually came from DeepCredentials: HTTPS protects the channel, but anyone who learns your webhook URL (through logs, error trackers, leaked configs, etc.) can hit it directly.

Algorithm: HMAC-SHA256(signing_secret, raw_request_body) → lowercase hex-encoded.

Only the raw body is signed. X-Webhook-Timestamp is not part of the signed input, and DeepCredentials enforces no timestamp tolerance. To reject replayed requests, compare the body's signed timestamp field with your clock and choose your own tolerance.

EXPECTED=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | awk '{print $2}')
if [ "$SIGNATURE_HEADER" = "$EXPECTED" ]; then
  echo "Valid"
fi

import hashlib
import hmac

def verify_signature(body: bytes, secret: str, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# In your webhook handler:
is_valid = verify_signature(
    body=request.body,
    secret="YOUR_SIGNING_SECRET",
    signature_header=request.headers["X-Webhook-Signature"],
)

const crypto = require("crypto");

function verifySignature(body, secret, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  if (typeof signatureHeader !== "string" || signatureHeader.length !== expected.length) {
    return false;
  }
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// In your webhook handler:
const isValid = verifySignature(
  req.rawBody,
  "YOUR_SIGNING_SECRET",
  req.headers["x-webhook-signature"]
);

To rotate the signing secret without dropping events:

1. Click Rotate Secret in the portal webhook settings.
2. Copy the new secret.
3. For 24 hours after rotation (the grace period), DeepCredentials sends two signature headers:
   • X-Webhook-Signature — signed with the new secret.
   • X-Webhook-Signature-Previous — signed with the old secret.
4. Update your verification logic to check both headers.
5. Once your code uses the new secret, remove the old secret from your configuration. After the grace period, X-Webhook-Signature-Previous is no longer sent.

Webhook delivery currently makes one HTTP attempt per event, with a 10-second timeout. A timeout, connection error, or non-2xx response is logged and then discarded; there is no delivery persistence, retry queue, or replay API. Callbacks can therefore be missed.

Treat every callback as a slim progress hint, not as the authoritative resource or a guaranteed delivery stream. Reconcile through authenticated B2B reads:

• Poll the verification session or credential offer (GET by ID) while your workflow is active.
• Use invitation list filters and GET /b2b/v1/credential-invitations/{invitationId} to reconcile invitation state.
• Do not depend on callbacks arriving in a particular order. The redeemed invitation hint carries offer_id so you can follow the correct offer independently.

• Respond quickly — Return a 2xx status within 10 seconds (the delivery timeout). Process the event asynchronously if the work takes longer.
• Verify signatures (recommended) — Validating the HMAC is the only way to confirm the request originated from DeepCredentials. Skipping it is supported but leaves your endpoint trusting any caller who knows the URL.
• Reconcile from the API — Fetch the resource through its authenticated GET endpoint before making a final business decision, and use polling or scheduled reconciliation to cover missed callbacks.
• Protect captured payloads — If you retain raw request bodies for signature verification or audit, apply your normal access controls and retention policy even though lifecycle callbacks are slim.

• Verification Flow — Understand the full session lifecycle.
• Error Handling — Handle error events in webhooks.