How Do I Secure My Webhooks in Zoho Subscriptions?

Securing your webhooks can help verify that the webhooks were actually sent from Zoho Subscriptions.

To do this, you’d have to set up your server in such a way that it listens for webhooks from Zoho Subscriptions. When your server receives a webhook from Zoho Subscriptions, a hash value will have to be generated based on the payload and your secret token. Once done, check if it matches the hash value from Zoho Subscriptions and thereby validate the source of the webhook. This can add a layer of security by enabling your server to disregard third-party webhooks pretending to originate from Zoho Subscriptions.

To secure your webhooks:

• Go to Settings > Automation > Webhooks.
• Click + New Webhook.
• Mark the I want to secure this webhook box.
• Enter a Secret Token of your choice. It must be alphanumeric and range between 12-50 characters.

• Click Save to set up the webhook.

Now, the webhook will be sent with a hash value in its header (X-Zoho-Webhook-Signature).

Validating the Webhook from Your Side

When your server receives the webhook, a hash value will have to be generated for the payload, in the same way that Zoho Subscriptions generated it. This is necessary to produce the same hash value to validate the webhook.

The following parameters (if available) need to be used to generate the hash value:

• Query string parameters.
• Default payload/Customized raw JSON payload.
• x-www-form-urlencoded payload (key-value pairs).

Construct a string by sorting the payload’s key-value pairs in alphabetical order. The pairs must be sorted in an alphabetical order with respect to their keys.

Points to remember while constructing the string:

• If your webhook contains query string parameters, ensure that those key-value pairs are sorted along with the payload’s key-value pairs.
• There cannot be any spaces between the key-value pairs.

Once you’ve sorted the key-value pairs and constructed the string, append the raw JSON to the end of the string.

For example, this is how you’d construct a string for a webhook with query string parameters and a default payload:

Query string parameters’ key-value pairs:

subscription_id=90343, name=basic 

Default payload/raw JSON:

{"created_date":"2019-03-06","event_id":"5675"}

The constructed string would be:

namebasicsubscription_id90343{"created_date":"2019-03-06","event_id":"5675"}

Here’s another example for a webhook that contains query string parameters and an x-www-form-urlencoded payload:

Query string parameters’ key-value pairs:

customer_name=Bowman, status=active

x-www-form-urlencoded payload’s key-value pairs:

addon_description=Monthly addon, quantity=1

The constructed string would be:

addon_descriptionMonthly addoncustomer_nameBowmanquantity1statusactive

The hash value can be computed by applying the HMAC-SHA256 algorithm on this string, along with the secret token that was used in Zoho Subscriptions.

You can then proceed to validate the webhook by checking if the hash value computed form your side matches with the one in the header (X-Zoho-Webhook-Signature) of the webhook from Zoho Subscriptions.