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.
• 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.
2. Select your organization.
3. Navigate to Settings > Webhooks.
4. Enter your Webhook URL (must be HTTPS).
5. Click 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 first-time setups receive the same firehose as before.
• 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.

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 locked or revoked credential from a clean one before the follow-up GET. 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.

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, captured credential_subject_data, 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}' \
  -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) → hex-encoded.

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");
  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. During the grace period, the gateway 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.

Webhook delivery currently makes one synchronous HTTP attempt. 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 or get the verification session and credential offer 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.