Get Webhook

Read a webhook subscription visible in the authenticated owner scope.

Endpoint

POST /v3/webhooks/get

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`	Yes	Webhook event enum.
`subscription_id`	No	Exact subscription selector. Send a returned `webhook_id` here.
`account_number`	Conditional	Required or forbidden by the owner/event policy.

Success data

A webhook object containing webhook_id, event_type, callback_url, status, created_at, and updated_at. The current response mapper does not populate subscription_id, account_number, or suspend_reason.

Behavior and validation

This is a synchronous read. Use subscription_id for deterministic selection when more than one record could match the event 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:

field_required for missing required selector context.
permission_denied for an unsupported owner/event/account combination.
not_found when no visible subscription matches.

Example request

curl --request POST "${BASE_URL}/v3/webhooks/get" \
  --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":1,"subscription_id":"wh_demo_001","account_number":"acct_demo_001"}'

Example response

{"code":200,"message":"success","data":{"webhook":{"webhook_id":"wh_demo_001","event_type":"PIX_PAYMENT_IN","callback_url":"https://webhook.example.test/pagsmile","status":1,"created_at":1710000000000,"updated_at":1710000100000}},"time":1710000100100}

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