> ## 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 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](/guides/testing-in-sandbox).

## 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 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.
  </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.

    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](/guides/testing-in-sandbox).
  </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. This replays 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 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](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
* [Testing in sandbox](/guides/testing-in-sandbox) — magic values to force specific sandbox outcomes
* [Subscribe to events](/webhooks/subscribe) — full subscription lifecycle
* [Retry policy](/webhooks/retry-policy) — replaying past deliveries against updated handlers