Test webhook notifications

This guide helps you verify both outgoing and incoming webhook handling in the sandbox. It uses predefined counterparty wallets and deterministic name/address matching rules to produce DELIVERED, CONFIRMED, or DECLINED outcomes.

Use the following test counterparty identities when creating OUTGOING sandbox transactions. Matching the friendly name with the address produces a CONFIRMED update; using a different name with a listed address produces a DECLINED update. (Comparisons are case-insensitive.)

These are the core sandbox wallets available to all tenants.

Additional monitoring-only addresses exist that will not trigger status updates, but will result in a DELIVERED status of an outgoing transaction:

1. Create an outgoing Travel Rule transaction from your sandbox tenant (via API or UI).
2. Set the destination wallet address, asset and blockchain to one from the table above.
3. Set the beneficiary name to the matching Friendly name.
4. Ensure your tenant has a webhook URL configured in the Client Dashboard under Settings → Webhooks.

Expected results

• The transaction is created and initially shown as DELIVERED.
• A subsequent update from the "beneficiary VASP" will set the transaction to CONFIRMED and you will receive a webhook notification about the update. If the beneficiary name doesn’t match the entry for that address, the webhook will update the transaction to DECLINED and include a status reason.

You can emulate inbound Travel Rule traffic entirely in the sandbox using our public simulation endpoint. This does not require any on-chain activity.

Endpoint

POST https://cryptoswift-webhook-responder-136879662199.europe-north1.run.app/simulate/outgoing

Headers

• Content-Type: application/json
• x-api-key: <YOUR TEST ENVIRONMENT API KEY>

Body: provide payload data that maps to one of the wallets in your My Wallets list:

{
  "asset": "ETH",
  "blockchain": "Ethereum",
  "destination": "0xabcdef1234567890abcdef1234567890abcdef12",
  "beneficiary": {
    "type": "NATURAL",
    "name": "John Smither",
    "accountNumber": "AC-123"
  }
}

cURL example

curl -X POST \
  'https://cryptoswift-webhook-responder-136879662199.europe-north1.run.app/simulate/outgoing' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_TEST_API_KEY' \
  -d '{
    "asset": "ETH",
    "blockchain": "Ethereum",
    "destination": "0xabcdef1234567890abcdef1234567890abcdef12",
    "beneficiary": {
      "type": "NATURAL",
      "name": "John Smither",
      "accountNumber": "AC-123"
    }
  }'

Behaviour

• If the destination wallet matches one of your custodial wallets (asset, blockchain, address combination), you will receive an incoming Travel Rule message from one of the wallets in the table above.
• If you have set up a webhook notification URL, your backend will be notified about the incoming transaction.

You can validate self-hosted wallet verification end to end with either integration path:

• Embed the component or widget: Use the hosted web component or self-hosted widget flow and trigger a verification session with the API. Launching the flow from your UI mirrors the production experience and lets you confirm that webhooks and callbacks are handled correctly.
• Start from the Client Dashboard: Navigate to Wallet Verifications → Create to generate a verification session without writing code. The dashboard returns a ready-to-use URL that you can share with testers or open directly.

For manual testing, generate a dedicated wallet in MetaMask (or another wallet app) and follow the prompts in the verification flow. Signing with a real key pair ensures you cover the entire signature challenge, even though no blockchain transfer occurs.

Status change events from these verifications are delivered via your webhook subscription. Make sure your integration handles the payloads described in Receive notification via webhook so you can react to users completing, failing, or cancelling the challenge.

• No webhooks received: verify your webhook URL is set and publicly reachable.
• Only DELIVERED or PENDING: ensure the address and friendly name match exactly (case-insensitive) one of the table entries above.
• 403 calling simulation endpoint: confirm you are using the Test Environment API key in the x-api-key header.

• Review the Webhooks guide for payload structure.
• Test the Wallet verification widget to mirror the hosted experience.
• Review the Wallet verification API for programmatic integration examples.
• Revisit the API reference when you need production-ready request examples.