Webhooks

Webhooks provides a way for notifications to be delivered to your server in real time whenever an event occurs on RedCarbon.

To ensure that your server only processes webhook deliveries that were sent by RedCarbon and to ensure that the delivery was not tampered with, you should validate the webhook signature before processing the webhook payload.

This will help you avoid spending time and resources processing webhook deliveries that are not genuine and will help avoid man-in-the-middle attacks.

To do this, you need to:

1. Create a Webhook and retrieve its secret token.
2. Store the token securely on your server.
3. Validate incoming payloads against the token, to ensure that they were sent by RedCarbon and have not been tampered with.

Validating webhook deliveries

RedCarbon will use your secret token to create a hash signature that's sent to you with each request. The hash signature will appear in each delivery inside the value of the X-RedCarbon-Signature header.

The value of the X-RedCarbon-Signature header is something like t=1620000000,v1=000000000000. The t parameter is the Unix timestamp of when the event has been generated. The v1 parameter is the hash signature.

In your code that handles the webhook payload, you should calculate a hash signature and compare it with the one inside the v1 parameter. To calculate the hash signature, you need to:

1. Concatenate the timestamp and the payload body into a single string with a dot separator. For example, 1620000000.{"event":"ticket.created","data":{"id":"ord_000000000000"}}.
2. Calculate the HMAC SHA-256 hash of the string using your secret token as the key.
3. Compare the hash signature you calculated with the one inside the v1 parameter.

There are a few important things to note:

• RedCarbon uses an HMAC hex digest of the SHA-256 hash algorithm.
• The hash signature is generated using the payload body and the timestamp in the t parameter. Not the timestamp inside the payload body.