We are excited to introduce a new feature for SimpleSwap Affiliate Partners using our API: Webhooks. This feature allows you to receive real-time notifications on the status of your crypto exchanges, so you do not have to send API requests every time.

This guide is about what webhooks are, how to use them, and how to set them up in your Affiliate account.

What is a Webhook

A webhook is a way for an app to provide users with real-time information. Rather than having to pull information via API requests, webhooks give you information about the status of exchanges instantly, providing a more efficient and timely update mechanism.

How to Use Webhooks

Setting up webhooks is not as difficult as it might sound. Here is what you need to:

• Sign in to your Affiliate account on our website. Then go to the Webhook section within the Hub tab.

• In the provided URL line, insert the address of your service endpoint located on your server. The URL should respond with a status code 200 to acknowledge receipt of the webhook data.

• Click the Save button and generate a unique secret key. This key is crucial for validating the data sent via the webhook, ensuring its authenticity and security.

Important: We do not store this secret key. Make sure to keep it secure and accessible. 

• Use the "Send an Example" button to check if your webhook is working correctly. This will send a test notification to your endpoint.

• Implement an algorithm on your server to handle the webhook data. You can define the rules and logic for processing and presenting this information according to your needs.

In cases where a webhook request was not successfully delivered, you can resend the request.

You can view the history of all webhook requests from the past 90 days in your account. You can also export this data. 

Signature Verification Rules

To ensure the data's integrity and authenticity, verify the webhook's signature:

• Concatenate the strings messageId, publicId, status, and webhookSecret, separated by underscores.

• Compute the SHA-1 hash of the concatenated string. The result should be in hexadecimal representation.

Let’s look at the example.

Given the webhookSecret:

webhookSecret = BmSvGmnr6NPz

And the following webhook payload:

{

   "messageId": "cf6fc203ba047a9ef14e02bba985e747",

   "publicId": "testExchange",

   "status": "finished"

}

Concatenate the strings:

cf6fc203ba047a9ef14e02bba985e747_testExchange_finished_BmSvGmnr6NPz

Compute the SHA-1 hash of the concatenated string:

sha1("cf6fc203ba047a9ef14e02bba985e747_testExchange_finished_BmSvGmnr6NPz") = 749ee5318093cdc07708da65d9eb581e949acf40

After computing the SHA-1 hash of the concatenated string, compare this hash with the ‘verifyToken’ received in the webhook payload. This comparison ensures that the data has not been tampered with and verifies its authenticity. 

Security

Using the secret key to validate the data sent via the webhook ensures that the data is from our exchange. This stops unauthorized access and makes your account more secure.

Since we do not keep a copy of your secret key, it is essential to store it securely. If you think the key has been compromised, regenerate it in your account. To do so, press the button with a key on it.

Learn more in the Affiliate Program Terms of Service. If you have any questions, contact our support team.