Skip to main content

Configure webhook delivery for an onboarding case

PUT 
/v1/onboarding-cases/:case_id/webhook-setup

Saves the webhook subscription the platform creates for your bank when onboarding is activated. Webhook delivery is required: the platform must be able to send you beneficiary.screening.requested events, so a case cannot be submitted without a complete webhook setup (readiness.webhook_ready).

Required scope: connector:onboarding:artifacts:write.

Allowed states: AWAITING_BANK_ADMIN, BANK_CONFIGURING, NEEDS_CHANGES (otherwise 409). The first edit moves AWAITING_BANK_ADMIN to BANK_CONFIGURING.

Each call replaces the whole setup. No Idempotency-Key is used; repeating a request has the same effect.

Fields (all in data.attributes):

  • enabled (required): must be true; false returns 400.
  • url (required): absolute https URL with a host that receives the callbacks. Returned as callback_url.
  • event_types (required, at least one, unique): must include beneficiary.screening.requested.
  • delivery_format (optional, default jsonapi): only jsonapi is accepted.
  • signing_secret (write-only): the shared secret used to sign each delivery so you can verify it. Must not be blank. The setup is incomplete until a secret has been supplied once; when omitted on a later call, the secret saved earlier is kept.
  • signing_secret_version (optional, default v1): label for the signing secret; 1 to 64 printable ASCII characters without spaces.
  • receiver_auth (optional): set it if your endpoint requires an OAuth 2.0 client-credentials access token. token_endpoint_url (absolute https URL), client_id and requested_scope are required and must not be blank; client_secret (write-only) must be supplied once for the setup to be complete and is kept when omitted later. Omitting receiver_auth removes receiver authentication and discards any saved client secret.

Secrets. Secrets are stored encrypted by the platform and are never returned. The case shows only signing_secret_configured and receiver_auth.client_secret_configured.

Validation order. Field format rules (enabled, url, event_types, delivery_format, blank secrets) are checked before authorisation and return 400 with a source.pointer. The secret-version format is checked afterwards and returns 422.

The response is the updated case; the saved setup is in data.attributes.configuration.webhook_setup.

Request​

Responses​

The webhook setup was saved. Returns the updated case, including readiness.