Webhooks / API reference

Configure the institution's signed customer webhook endpoint

Request and response reference for POST /v1/webhook-endpoints.

POST/v1/webhook-endpoints

Authentication: API key

Use the base URL and access configuration provided to your institution. Examples are request templates, not transaction results. Field tables focus on client fields; preserve additional metadata returned by the configured service.

Request

Keep API keys in your backend. Required entitlements and institution scope still apply.

Request templatecURL

curl -X POST "$OSAI_API_BASE_URL/v1/webhook-endpoints" \
  -H "Authorization: ApiKey $OSAI_PUBLIC_ID:$OSAI_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <stable-operation-key>" \
  --data '{
  "endpoint_url": "<endpoint_url>",
  "signing_secret": "<signing_secret>",
  "subscribed_event_types": [
    "<value>"
  ]
}'

Parameters

Name	Location	Requirement	Description
`Authorization`	header · string	Required	Use the value defined for this resource.
`X-Request-Id`	header · string	Optional	Use the value defined for this resource.
`Idempotency-Key`	header · string	Required	Use the value defined for this resource.

Request body

Send JSON with Content-Type: application/json. Nested field names identify their parent object; required markers apply within that object. Replace template values using the relevant resource and configured instrument rules.

Field	Type	Description & constraints
`endpoint_url`Required in parent object	`string`uri	Defined by the resource contract.
`signing_secret`Required in parent object	`string`	Customer-generated secret used to verify signed webhook deliveries.
`subscribed_event_types`Required in parent object	`array`	Defined by the resource contract.

Responses

Inspect HTTP status before parsing a body. These tables describe client response fields rather than invented successful transaction payloads.

200 · Webhook endpoint configured

Field	Type	Description & constraints
`configured`Required in parent object	`boolean`	Defined by the resource contract.
`request_id`Required in parent object	`string`	Defined by the resource contract.

400 · Validation failure

Field	Type	Description & constraints
`error`Required in parent object	`object`	Defined by the resource contract.
`error.code`Required in parent object	`string`	Defined by the resource contract.
`error.message`Required in parent object	`string`	Defined by the resource contract.
`error.request_id`Required in parent object	`string`	Defined by the resource contract.

403 · The institution is not entitled to configure webhooks

No client body fields are defined for this response.

409 · Idempotency conflict or request still in progress

No client body fields are defined for this response.

Retries & recovery

Keep the original request identifiers and any required idempotency key. A timeout does not establish failure. Read the original resource or command before another financial write; use expected versions for concurrent changes.

Error handling →Idempotency →