Skip to content

Get real-time updates using webhooks

Set up webhooks on your CryptoSwift account

CryptoSwift uses webhooks to notify your application when a Travel Rule transaction is sent to your account (incoming Travel Rule messages).

Webhooks are useful if you want to create a full integration between CryptoSwift and your own application and collect incoming Travel Rule transaction messages.

How webhooks are used by CryptoSwift

Webhooks enable CryptoSwift to push real-time notifications to your application. CryptoSwift uses a JSON payload that is sent over HTTPS to notify your application. Those notifications can be used to execute actions in your backend systems.

Receiving webhook notifications

You can start receiving event notifications in your app using the steps in this section:

  1. Create a webhook
  2. Register the webhook URL
  3. Handle requests from CryptoSwift
  4. Test that your webhook endpoint is working
  5. Secure your webhook endpoint

The key has to be put in a custom header called x-api-key.

1. Create a webhook

Create a webhook endpoint on your server that will accept incoming data. Make sure the URL is publicly accessible once deployed.

2. Register your webhook URL

Once the webhook endpoint has been created, register the webhook public URL for your CryptoSwift account using the API.

You can use the tenant/me PATCH endpoint and provide {"webhookUrl": "..."} object in the request body, or contact our support to help you out with that.

3. Handle requests from CryptoSwift

CryptoSwift uses a JSON payload to notify your application. For incoming Travel Rule transaction messages, the full Travel Rule message is forwarded to your application. See the Travel Rule data model for more details.

Inside your application make sure to handle requests from CryptoSwift by parsing each event object and returning 2xx response status codes.

4. Test your webhook endpoint

Make sure your webhook endpoint is working properly. You can use the example webhook data provided below to test out your integration.

Example webhook request

curl --location --request POST 'YOUR-WEBHOOK-URL' \
--header 'cryptoswift-signature: t=1676540660052,s=a18b9a8c30b896374efa6d5f3026b0e36f249561e649fc94b5e500a7ef24d10d' \
--header 'Content-Type: application/json' \
--data-raw '{"id":"418fec4a-8ba6-4b35-9c05-a9aa80de31c4","status":"NEW","asset":"BTC","amount":69,"blockchainInfo":{"transactionHash":"6146ccf6a66d994f7c363db875e31ca35581450a4bf6d3be6cc9ac79233a69d0","origin":"0xb794f5ea0ba39494ce839613fffba74279579268","destination":"0x71C7656EC7ab88b098defB751B7401B5f6d8976E","destinationType":"CUSTODIAL"},"vaspInfo":{"beneficiaryVaspName":"SwiftCryptoExchange","beneficiaryVaspEmail":"info@SwiftCryptoExchange.domain","beneficiaryVaspExtraInfo":"Tel +372 1234 5678"},"originator":{"type":"NATURAL","name":"Guy Hillar","accountNumber":"04143282398","address":"Alexanderplatz 25, Berlin","country":"Germany","nationalIdentificatorType":"IDC","nationalIdentificator":"DE123456789","customerNumber":"A5433634","dateOfBirth":"1991","placeOfBirth":"Germany"},"beneficiary":{"type":"LEGAL","name":"Maria LLC","accountNumber":"AB54234232","country":"Estonia","nationalIdentificatorType":"IDC","nationalIdentificator":"EE11234566"}}'

5. Secure your webhook endpoint

Use webhook signatures to verify that it was indeed CryptoSwift that generated a webhook request and that it didn't come from a server acting like CryptoSwift. This is an optional but recommended step in order to guarantee a secure integration.

From the example request above you can see that a custom header called CryptoSwift-Signature is sent from CryptoSwift with each webhook notification. See webhook signatures to find out how to set up and validate webhook signatures.

Next steps