Skip to main content
WEBHOOK

Authorizations

Authorization
string
header
required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Body

application/json

Payload delivered for operation lifecycle events (OPERATION_REQUESTED, OPERATION_CUSTOMER_ACTION_REQUIRED, OPERATION_COMPLETED, OPERATION_FAILED). Inspect the X-Event-Type header — or currentState.status on the payload — to tell which transition fired. The intermediate PROCESSING status is not published as a webhook; fetch GET /v1/operations/{operationId} if you need it.

customerId
string<uuid>
required
Example:

"9c7b6a2e-1d3f-4a5b-8c9d-0e1f2a3b4c5d"

account
object
required

Reference to a customer account, including the registered owner name.

sourceAmount
object
required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library for arithmetic — never JavaScript Number.

destinationAmount
object
required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library for arithmetic — never JavaScript Number.

intent
Withdrawal · object
required

Operation intent. Discriminated by type.

fees
(Percentage · object | Absolute · object)[]
required

Fee charged on the operation. Discriminated by type.

transactions
PIX · object[]
required

Underlying rail transactions executed for this operation.

currentState
object
required

Status the operation is in at the time the event fires.

atTime
string<date-time>
required

When this event occurred. Distinct from the resource's createdAt — events fire on state transitions, so atTime reflects when the transition happened, not when the underlying resource was first created.

quote
object | null

Quote linked to the operation, when applicable. null for same-asset operations or operations without a quote.

tags
object[]

System-managed labels stamped onto the operation when it is created. Inherited from the account's propagating tags.

Example:

Response

200

Acknowledged. Trace Finance considers any 2xx response a successful delivery.