Bind a webhook to an auth profile

POST 
/v1/webhooks/:webhook_id/bind

Bind a webhook subscription to an OAuth2 receiver auth profile, so that every delivery to this subscription carries an access token from your own token endpoint. Requires the connector:auth-profiles:bind scope and an Idempotency-Key header.

Send data.type: webhooks and the auth_profile_id (a UUID) of a profile created with POST /v1/auth-profiles. Both the webhook and the auth profile must belong to the calling bank; otherwise the request fails with 400 and nothing changes. Binding again with a different auth_profile_id replaces the previous binding. There is currently no unbind request.

Effect. Once bound, before each delivery the platform obtains an access token from the profile's token endpoint with the OAuth2 client credentials grant (see POST /v1/auth-profiles) and sends it as Authorization: Bearer <token>, in addition to the HMAC signature. Binding also moves the subscription back to PENDING_VERIFICATION and sends a new webhook.verification event (with the bearer token). Business events are not delivered until your endpoint answers that event with a 2xx status and the subscription is ACTIVE again.

Request

Responses

202

Accepted. The binding is applied and the subscription is in PENDING_VERIFICATION until the new verification handshake succeeds.

400

auth_profile_id is not a UUID, the Idempotency-Key header is missing, or the webhook or the auth profile does not exist in the calling bank.

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.

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.