Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tracefinance-docs-withdrawal-beneficiary-events.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The sandbox environment delivers real webhook events as you exercise the API — creating orders, registering beneficiaries, initiating PIX payments, and so on. Use it to develop and test your handler before going to production. The sandbox base URL is https://api.sandbox.tracefinance.com.
1

Deploy your handler to your sandbox environment

Webhooks must reach a public HTTPS URL. Use the same sandbox or staging environment you use for the rest of your Trace integration testing — the same one that calls Trace’s sandbox API. Self-signed certificates and private networks are not supported.
2

Register a sandbox subscription

Point the subscription at your sandbox handler URL and pick the resources you want to test:
curl --request POST \
  --url https://api.sandbox.tracefinance.com/webhook/api/subscriptions \
  --header 'Authorization: Bearer <sandbox-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://api.sandbox.example.com/trace-webhooks",
    "includeAll": true,
    "allowRetry": true
  }'
3

Trigger events

Sandbox does not expose a synthetic-event endpoint. To generate events, drive the corresponding API:
  • Account events — complete sandbox account onboarding so an asset activates.
  • Beneficiary events — register a sandbox beneficiary and wait for the compliance review to settle.
  • Operation events — initiate sandbox operations (deposit, withdrawal, swap).
Sandbox transactions move through the same state machine as production but with a faster cadence and no real-money settlement, so you typically see the full event lifecycle within seconds.
4

Inspect deliveries

Use the execution logs endpoint to see exactly what was sent and what your handler responded with:
curl --request GET \
  --url https://api.sandbox.tracefinance.com/webhook/api/subscriptions/<subscription-id>/executionLogs \
  --header 'Authorization: Bearer <sandbox-token>'
Failed attempts can be resent on demand once you fix your handler — useful for replaying real payloads against new code without re-running the originating transaction.

​
Tips

  • Keep your sandbox subscription and production subscription in separate projects with their own client credentials. Signatures are bound to the client secret, so a sandbox key won’t validate production deliveries (and vice versa).
  • Track which subscription belongs to which environment by URL — point staging at your staging handler, production at your production handler.
  • If you want to receive sandbox events on a developer laptop for quick exploration, expose the local handler with a public HTTPS tunnel (for example, ngrok or Cloudflare Tunnel) and PATCH the subscription with the tunnel URL. Tunnel URLs typically change between sessions, so update the subscription each time.