Skip to content

Webhooks

Receive signed transaction and wallet verification updates and recover missed notifications.

CryptoSwift sends HTTPS JSON notifications for incoming messages, outgoing transaction updates, and wallet verification changes. Use webhooks for timely updates and API polling for reconciliation and recovery.

Delivery behavior

BehaviorWhat your handler must do
Requests have a 10-second timeout.Verify and durably store or queue accepted work, then return 2xx promptly.
Failed deliveries are logged but are not automatically retried.Run recovery polling; do not depend on a later notification to repair every missed update.
Notifications contain snapshots of a record.Allow later updates with the same record ID and retrieve the latest API state before making an irreversible decision.

1. Create a webhook

Expose a public HTTPS endpoint on your backend. Capture the raw request body for signature verification before JSON middleware changes it.

For incoming tests, register and confirm a few Sandbox wallets. Maintain your actual custodial wallet inventory in Production for live matching.

If you restrict source IPs, the CryptoSwift API addresses are:

  • Sandbox: 34.88.32.82
  • Production: 35.228.164.60

Source IP filtering complements signature verification.

2. Register your webhook URL

Set the URL under Settings → Webhooks in the Sandbox dashboard or Production dashboard. You can also call the Update tenant endpoint (Sandbox) or Update tenant endpoint (Production):

curl --request PATCH 'https://api-dev.cryptoswift.eu/tenant/me' \
  --header "X-Api-Key: $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "webhookUrl": "https://app.example.com/webhooks/cryptoswift" }'

This success response has no body. Do not parse it as JSON.

Register and test the URL separately in each environment. Setting the webhook URL generates a new webhookSecret; retrieve it from GET /tenant/me and refresh the secret stored by your handler. Follow the signature guide for the complete example.

3. Handle requests from CryptoSwift

  1. Verify CryptoSwift-Signature using the raw body and the receiving environment's secret.
  2. Parse the JSON only after verification and route using X-Event-Type.
  3. Durably save or queue the accepted work before returning 2xx.
  4. Upsert the record in your worker and reconcile the latest API state before acting.
X-Event-TypeRoute
transactionIncoming messages, automatically detected deposits, and outgoing or incoming data/status updates. Use direction to select the transaction workflow.
wallet-verificationOwnership, additional evidence, monitoring, and reviewer updates. Evaluate ownership and each required additional-step status separately.
ExampleTransaction status notificationWebhook POST
{
  "id": "233e3fd4-2ef0-477c-a398-8f993d131a19",
  "status": "CONFIRMED",
  "statusReasoning": null,
  "direction": "OUTGOING",
  "createdAt": "2026-07-31T09:42:18.519Z",
  "asset": "ETH",
  "amount": 0.059625001,
  "amountUsd": 223.41,
  "amountEur": 193.64,
  "metadata": "withdrawal-8472",
  "blockchainInfo": {
    "transactionHash": "0x8129df36bf862c55702ab3991c4cc6d00903dc7af4b6f1afc909c216f07e34bd",
    "origin": "0x1234567890abcdef1234567890abcdef12345678",
    "destination": "0xabcdef1234567890abcdef1234567890abcdef12",
    "destinationType": "CUSTODIAL",
    "blockchain": "Ethereum",
    "isDestinationConfirmed": true,
    "destinationWalletId": 7069
  },
  "vaspInfo": {
    "originatorVaspName": "Originator VASP",
    "originatorVaspEmail": "support@originator.example",
    "beneficiaryVaspName": "Beneficiary VASP",
    "beneficiaryVaspEmail": "support@beneficiary.example",
    "beneficiaryVaspExtraInfo": null
  },
  "originator": {
    "type": "NATURAL",
    "name": "Diana DueDiligence",
    "accountNumber": "customer-123",
    "address": "873 Audit Alley",
    "country": "AU",
    "nationalIdentificatorType": null,
    "nationalIdentificator": null,
    "customerNumber": "customer-123",
    "dateOfBirth": null,
    "placeOfBirth": null
  },
  "beneficiary": {
    "type": "NATURAL",
    "name": "John Smither",
    "accountNumber": "AC-123",
    "country": "EE",
    "nationalIdentificatorType": null,
    "nationalIdentificator": null
  },
  "travelRuleMessageSource": "CryptoSwift",
  "riskScore": {
    "originatorRiskScore": 18,
    "originatorRiskSeverity": "low",
    "beneficiaryRiskScore": 12,
    "beneficiaryRiskSeverity": "low",
    "sanctions": {
      "originatorWallet": {
        "isSanctioned": false,
        "details": []
      },
      "beneficiaryWallet": {
        "isSanctioned": false,
        "details": []
      }
    }
  },
  "ruleEngine": {
    "decision": "PROCEED",
    "ruleEngineId": "6292e827-ce05-4cae-a3c8-43e1fb073e1e",
    "ruleId": "7f3db7f7-b5b4-4dd7-8de6-e6c15a6eb9e2",
    "ruleName": "Proceed with low-risk outgoing transfer",
    "conditions": {
      "all": [
        {
          "field": "riskSeverity",
          "operator": "EQ",
          "value": "low"
        }
      ],
      "any": []
    },
    "ruleEngineVersion": 3,
    "scope": "OUTGOING",
    "waitForSeconds": null,
    "onTimeoutDecision": null
  }
}
ExampleWallet verification notificationWebhook POST
{
  "id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
  "token": "<widget-token>",
  "url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
  "asset": "ETH",
  "blockchain": "Ethereum",
  "address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
  "metadata": "customer-123",
  "status": "VERIFIED",
  "flow": "SIGNATURE_PROOF",
  "allowedFlows": [
    "SIGNATURE_PROOF",
    "VISUAL_PROOF",
    "SELF_DECLARED"
  ],
  "reuse": null,
  "expiresAt": "2026-11-12T09:00:00.000Z",
  "createdAt": "2026-11-11T09:00:00.000Z",
  "satoshiFlow": {
    "amount": null,
    "depositAddress": null
  },
  "statusReasoning": null,
  "riskScore": null,
  "warnings": [],
  "origin": "https://app.example.com",
  "redirectUrl": null,
  "signature": "<0x-prefixed-signature>",
  "message": "CryptoSwift wallet ownership verification | verificationId: <verification-id> | nonce: <cryptographically-random-nonce> | issuedAt: <ISO-8601-timestamp>"
}

The id is a transaction or verification ID, not a unique delivery ID. Do not discard every later payload with an ID you have already seen. Make repeated processing safe, while accepting genuine subsequent updates. Do not assume delivery order; stale snapshots should not overwrite the latest reconciled state.

See payload examples and the transaction field reference. Some incoming participant fields remain hidden until the destination wallet is confirmed.

4. Secure your webhook endpoint

Use the signature verification example for raw-body handling, HMAC validation, and replay tolerance. Keep API keys and webhook secrets on your backend. Route longer work through your queue so verification and receipt complete within the request timeout.

Recover missed updates

Discover new incoming transaction IDs with GET /transactions and a paginated creation-time window. Separately poll known records that are still awaiting delivery, review, a hash, or another expected update. _from and _to filter creation time; a recent window will not find changes to an older record.

Follow the complete reconciliation pattern. For wallet verifications, poll the verification IDs your backend created until ownership and required additional steps have the results your policy needs.

Optional Notabene network setup

If you use the Notabene network, follow the external network setup. This forwards network notifications into CryptoSwift and is separate from the callback URL where CryptoSwift notifies your application.

Next steps