List Webhooks

List webhook subscriptions visible to the authenticated credential owner.

Endpoint

POST /v3/webhooks/list

Authentication and target

Access is resolved through the authenticated credential owner. Account credentials can target only their own account. User credentials must supply account_number for transaction events and omit it for VA Account KYB. Platform credentials can manage only Master Account KYB and must omit account_number. See Webhook Management for the complete event/owner matrix. Do not send X-ISPB or X-Account-Number with a platform or user credential. An account credential may omit both headers; if sent, both are required and must match its bound account.

Request body

Field	Required	Description
`event_type`	No	Event filter. Omit it to list the allowed owner scope.
`account_number`	Conditional	Required or forbidden by the owner/event policy.
`subscription_id`	No	Present in the contract but currently ignored by List.

Success data

webhooks[]; each item contains webhook_id, event_type, callback_url, status, created_at, and updated_at.

Behavior and validation

This endpoint is not paginated. Account-scoped list explicitly asks for active configurations; do not assume identical filtering for every other owner scope.

Errors

Every call can fail for missing or invalid signature headers, an expired timestamp, nonce replay, an invalid body hash or signature, insufficient permission, or a downstream service error. Endpoint-specific errors include:

permission_denied for a disallowed owner/event/account combination.

Example request

curl --request POST "${BASE_URL}/v3/webhooks/list" \
  --header "Content-Type: application/json" \
  --header "X-Client-ID: ${CLIENT_ID}" \
  --header "X-Timestamp: ${TIMESTAMP_MS}" \
  --header "X-Nonce: ${NONCE}" \
  --header "X-Signature: ${SIGNATURE}" \
  --data '{"event_type":5}'

Example response

{"code":200,"message":"success","data":{"webhooks":[{"webhook_id":"wh_demo_002","event_type":"VA_ACCOUNT_KYB","callback_url":"https://webhook.example.test/kyb","status":1}]},"time":1710000400000}

Getting started

API Reference

Webhooks

PIX Refund Lifecycle

Endpoint

Authentication and target

Request body

Success data

Behavior and validation

Errors

Example request

Example response

​Endpoint

​Authentication and target

​Request body

​Success data

​Behavior and validation

​Errors

​Example request

​Example response

Endpoint

Authentication and target

Request body

Success data

Behavior and validation

Errors

Example request

Example response