Test webhooks in sandbox

Develop and verify webhook handlers against the Trace Finance sandbox.

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 is https://api.sandbox.tracefinance.com. 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:

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/v1/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.

   These follow the happy path by default. To drive a rejection, a failure, or a stuck pending state instead, submit the magic values in Testing in sandbox.

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/v1/subscriptions/<subscription-id>/executionLogs \
     --header 'Authorization: Bearer <sandbox-token>'
   

   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.

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