Validating webhook deliveries

Once your server is configured to receive webhook payloads, it will listen for any delivery that's sent to the configured endpoint. To ensure that your server only processes webhook deliveries that were sent by xChange and to ensure that the delivery was not tampered with, you should validate the webhook signature before processing the delivery further. This will help you avoid spending server time to process deliveries that are not from xChange and will help avoid man-in-the-middle attacks.

Obtaining a secret

Please get in touch with your CDS account manager about obtaining a secret token to use for validating webhook deliveries.

IMPORTANT

After receiving the secret token, you should store it in a secure location that your server can access. Never hardcode a token into an application or push a token to any repository.

Validating webhook deliveries

xChange will use your secret token to create a hash signature that's sent to you with each payload. The hash signature will appear in each delivery as the value of the CDS-Webhook-Signature header.

In your webhook endpoint that handles deliveries, you should calculate a hash using your secret token. Then, compare the hash that xChange sent with the expected hash that you calculated and ensure that they match.

There are a few important things to keep in mind when validating webhook payloads:

• xChnage uses a HMAC base64 digest to compute the hash.
• The hash signature always starts with sha256=.
• The hash signature is generated using your webhook's secret token and the payload contents.

What should my endpoint return?

Signatures match

You should return a 200 HTTP status code.

Signagures don't match

You should return a 500 HTTP status code.