Skip to main content
PATCH
curl
rotate_secret_key rotates only the application-level secret, which signs deliveries to the legacy webhook_url. Every webhook destination signs with its own secret_shared_key, which this call does not change.
The retention fields are the same policy you set in Business Console → App Settings → Data. Read Data retention before you change them, in particular biometric template retention. allowed_return_hosts is described in Register your return destination. To read the current values first, call Get Webhook Configuration.

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Body

application/json

Send only the fields to change. Destinations are not managed here.

webhook_url
string<uri> | null

Legacy application-level webhook URL. Didit uses it only while the application has no enabled destination, and then only for status.updated and data.updated. It does not create a destination, and the next create, update or delete of a destination replaces it. To receive webhooks, create a destination with POST /v3/webhook/destinations/ instead.

Maximum string length: 2000
webhook_version
enum<string>

Payload version of the legacy webhook_url.

Available options:
v1,
v2,
v3
rotate_secret_key
boolean
default:false

true replaces the application-level secret_shared_key with a new random value at once; the new value is in the response. Destination secrets are not changed. Every call with true generates a new secret, so it is not idempotent.

capture_method
enum<string>

Legacy application setting. The verification flow does not read it.

Available options:
MOBILE,
MOBILE_AND_DESKTOP
data_retention_months
integer | null

Automatic deletion window in months (a month counts as 30 days), or null for no automatic deletion. A change applies to existing sessions too: every user verification session older than the new window is deleted automatically, and that deletion is irreversible.

Required range: 1 <= x <= 120
face_retention_policy
enum<string>

What happens to a session's face embedding when the session is deleted. retain_until_user_deleted needs face_retention_days in the same request or already set. A change applies to session deletions from then on; it creates or purges no existing biometric template.

Available options:
delete_with_session,
retain_until_user_deleted
face_retention_days
integer | null

Retention period, in days, of biometric templates under retain_until_user_deleted.

Required range: 1 <= x <= 3650
allowed_return_hosts
string[]

Replaces the whole list of Digital ID wallet return hosts. Bare hostnames only, such as shop.example.com: no scheme, port, path or wildcard. Values are lowercased and duplicates are dropped. Send [] to clear the list.

Maximum array length: 20
Maximum string length: 253

Response

The full configuration after the update, the same shape as GET /v3/webhook/. When you rotated the secret, store the new secret_shared_key before you discard the response.

Application-level webhook configuration, retention policy and Digital ID wallet return hosts, with every webhook destination.

webhook_url
string<uri> | null
required

Application-level (legacy) webhook URL. Didit sends to it only while the application has no enabled destination, and then only status.updated and data.updated. Every create, update or delete of a destination sets it to the URL of the oldest enabled destination, or null when none is enabled.

webhook_version
enum<string>
required

Payload version of the legacy webhook_url. Each destination has its own webhook_version.

Available options:
v1,
v2,
v3
secret_shared_key
string
required

Application-level signing secret (43-character URL-safe token). It signs only deliveries to the legacy webhook_url; each destination signs with its own secret_shared_key. API-key callers always receive it in full; Console users without read:webhooks receive an empty string.

capture_method
enum<string>
required

Legacy application setting. The verification flow does not read it: capture options are configured per workflow.

Available options:
MOBILE,
MOBILE_AND_DESKTOP
data_retention_months
integer | null
required

Automatic deletion window. User verification sessions created more than this many months ago (a month counts as 30 days) are deleted automatically, and that deletion is irreversible. null means sessions are never deleted automatically. See Data retention.

Required range: 1 <= x <= 120
face_retention_policy
enum<string>
required

What happens to a session's face embedding when the session is deleted. delete_with_session (default) deletes it with the session. retain_until_user_deleted is the opt-in biometric template retention: an image-free biometric template linked to the User is managed separately until its retention period ends, the User is deleted, or you purge it.

Available options:
delete_with_session,
retain_until_user_deleted
face_retention_days
integer | null
required

Retention period, in days, of biometric templates under retain_until_user_deleted. Required when that policy is set.

Required range: 1 <= x <= 3650
available_events
object[]
required

Every event type a destination can subscribe to, with a display label.

allowed_return_hosts
string[]
required

Hostnames (exact match, HTTPS only) a standalone Digital ID wallet verification may send the user back to with its return_url. Your white-label domain is always allowed as well. See Register your return destination.

Maximum array length: 20
Maximum string length: 253
endpoints
object[]
required

Every webhook destination of the application, oldest first, each with its signing secret. Read only here: manage destinations with the /v3/webhook/destinations/ endpoints.