Overview
The sandbox environment delivers real webhook events as you exercise the API: opening accounts, registering beneficiaries, initiating PIX payments, and so on. Use it to develop and test your handler before going to production. The sandbox base URL ishttps://api.sandbox.tracefinance.com. Sandbox already sends the delivery format with the event metadata in the body and the Webhook-* headers, so build your handler against it. To force a specific outcome (a rejection, a failure, a stuck pending state) instead of the default happy path, the sandbox accepts a set of magic values documented in Testing in sandbox.
Recommended workflow
1
Deploy your handler to your sandbox environment
Webhooks must reach a public HTTPS URL. Use the same sandbox or staging environment as the rest of your Trace Finance homologation, the one that calls Trace Finance’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:
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).
4
Inspect deliveries
Use the execution logs endpoint to see exactly what was sent and what your handler responded with. Each log’s Failed attempts can be resent on demand once you fix your handler. This replays real payloads against new code without re-running the originating transaction.
payload is the delivered body — type, resource, customerId, timestamp and the event in data — and its messageId is the Webhook-Id: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 and 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.
Related
- Environments — sandbox and production base URLs
- Testing in sandbox — magic values to force specific sandbox outcomes
- Subscribe to events — full subscription lifecycle
- Retry policy — replaying past deliveries against updated handlers