Webhooks & status synchronization

CryptoSwift sends Partner webhook notifications when a supported Partner-originated Travel Rule transaction is updated. This is mainly used for status updates, for example when a CryptoSwift client confirms or declines a Partner -> CryptoSwift Travel Rule message.

Partner webhook updates intentionally strip personal details to preserve privacy boundaries. They do not include IVMS101 data or other personal data. The payload carries transaction metadata and state tags such as PENDING, DELIVERED, CONFIRMED, DECLINED, and FAILED.

Set webhookUrl using PATCH /partners/me. CryptoSwift generates a webhookSecret, which you retrieve with GET /partners/me.

CryptoSwift sends an HTTP POST request to the configured webhookUrl.

Headers:

X-Event-Type: transaction
CryptoSwift-Signature: t=<timestamp>,s=<signature>

The CryptoSwift-Signature header is generated using HMAC SHA-256 over the timestamp and raw body payload:

payload_to_sign = <timestamp> + "." + <raw JSON request body>
signature = HMAC-SHA256(payload_to_sign, webhookSecret)

The t value is a Unix timestamp in milliseconds; s is a lowercase hex-encoded signature.

{
  "id": "86cc6fd8-caac-4b13-bb84-5d58e5d6d0cc",
  "status": "CONFIRMED",
  "statusReasoning": "Confirmed by beneficiary",
  "asset": "BTC",
  "amount": 0.1,
  "blockchainInfo": {
    "transactionHash": "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",
    "origin": "17SkEw2md5avVNyYgj6RiXuQKNwkXaxFyQ",
    "destination": "1MLh2UVHgonJY4ZtsakoXtkcXDJ2EPU6RY",
    "destinationType": "CUSTODIAL",
    "blockchain": "Bitcoin"
  },
  "createdAt": "2026-06-02T10:00:00.000Z"
}

Use the id field to match the notification to the Travel Rule transaction previously created through the Partner integration. Process status updates idempotently so operational replays do not cause duplicate side effects.

To test Partner webhook notifications in the Sandbox, send Partner Travel Rule messages to the known responding sandbox wallets listed in the Testing webhook notifications guide.

That guide lists wallet addresses, assets, blockchains, and expected response behavior. It does not list the Partner beneficiary VASP IDs directly. Use GET /partners/vasps/by-wallet with the test wallet address, blockchain, and asset to resolve the matching beneficiary VASP and retrieve the public key needed for encryption. Then send your POST /partners/transactions request to that resolved VASP.

When the sandbox beneficiary VASP responds, CryptoSwift sends a Partner webhook notification to your configured webhookUrl. Matching test data should produce a CONFIRMED update; intentionally mismatched beneficiary data can produce a DECLINED update, depending on the test wallet scenario.

Verify the header against the original raw body before parsing JSON. Use the backend verification example with your Partner webhookSecret; it covers malformed headers, constant-time comparison, and the recommended five-minute replay tolerance.