Rotate the webhook signing secret

POST 
/v1/webhooks/:webhook_id/rotate-secret

Register a new signing secret for a subscription and schedule when it takes over. Requires the connector:webhooks:rotate-secret scope and an Idempotency-Key header.

Like the initial secret, the new secret is chosen by your bank, is write-only and is never returned. Give it a new secret_version label (1 to 64 printable ASCII characters without spaces) so you can tell the secrets apart.

How the switch works. Every delivery is signed with exactly one secret, the active one, and names it in the X-DAN-Secret-Version header.

• Before activate_at, deliveries keep using the current secret.
• From activate_at (a time in the past or now means immediately) the new secret becomes active. The platform checks for due secrets about every 10 seconds and caches the active secret for up to 30 seconds, so deliveries signed with the previous version can still arrive for up to about a minute after activate_at. Retries of older events are re-signed with whichever secret is active at the time of the attempt.
• The previous secret is kept as retiring for grace_period_seconds after activation and then expires. Send 0 to use the platform default of 86400 seconds (24 hours). Negative values are rejected.

Zero-downtime rotation. Deploy the new secret to your verifier first, keyed by its secret_version, while still accepting the old one. Then call this endpoint. Choose the secret by the X-DAN-Secret-Version header of each request, and remove the old secret once you no longer receive deliveries signed with it.

Request

Responses

202

Accepted. The new secret version is stored and activates at activate_at.

400

secret is empty, secret_version is invalid, grace_period_seconds is negative, webhook_id is not a UUID, or the Idempotency-Key header is missing.

401

The bearer token is missing, malformed, expired, signed by an unknown key, or was not issued by the platform IAM for the Lyriq Connector. Obtain a new token and retry. See the Authentication section.

403

The token is valid but may not perform this request: it lacks the required scope, has no bank membership, needs an x-dan-bank-id header to choose between several memberships, names a bank in x-dan-bank-id it has no membership for, or the caller's bank is suspended or terminated. A new token with the same configuration fails the same way. See the Authentication section.

404

The resource does not exist, or it belongs to another bank. The Lyriq Connector does not distinguish the two cases, so resources of other banks are never disclosed.

409

The request conflicts with an earlier request or with the current state of the target: an Idempotency-Key reused with a different body (IDEMPOTENCY_CONFLICT), a request with the same key still in progress (IDEMPOTENCY_PENDING), or a target resource in a state that does not allow the request (STATE_CONFLICT).

422

The request is well-formed JSON but cannot be processed: the body does not match the expected shape (a missing or unknown member, a wrong type, or a wrong data.type), or it breaks a business or cross-field rule. Correct the request before retrying.

429

The request was refused because a rate limit was reached (code RATE_LIMITED). No Retry-After header is sent; retry with exponential backoff.

503

The request could not be served right now. Either the network is not fully operational (OUTBOUND_HALTED or READ_ONLY: mutations are refused while read endpoints keep working; OPERATIONAL_STATE_UNKNOWN: the state could not be determined), or a platform dependency is temporarily unavailable. No Retry-After header is sent; retry later with backoff. When retrying a mutation, reuse the same Idempotency-Key and body.