> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test 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 — 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`.

## Recommended workflow

<Steps>
  <Step title="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 Finance integration testing — the same one that calls Trace Finance's sandbox API. Self-signed certificates and private networks are not supported.
  </Step>

  <Step title="Register a sandbox subscription">
    Point the subscription at your sandbox handler URL and pick the resources you want to test:

    ```bash theme={"theme":"tokyo-night"}
    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
      }'
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Inspect deliveries">
    Use the [execution logs](/api-reference/fx-webhook/subscriptions/list-execution-logs) endpoint to see exactly what was sent and what your handler responded with:

    ```bash theme={"theme":"tokyo-night"}
    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](/webhooks/retry-policy#manual-replay) once you fix your handler — useful for replaying real payloads against new code without re-running the originating transaction.
  </Step>
</Steps>

## 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](https://ngrok.com) or [Cloudflare Tunnel](https://www.cloudflare.com/products/tunnel/)) and [PATCH the subscription](/api-reference/fx-webhook/subscriptions/update-subscription) with the tunnel URL. Tunnel URLs typically change between sessions, so update the subscription each time.

## Related

* [Environments](/guides/environments) — sandbox and production base URLs
* [Subscribe to events](/webhooks/subscribe) — full subscription lifecycle
* [Retry policy](/webhooks/retry-policy) — replaying past deliveries against updated handlers