Sapling - Use Webhook Token to Validate Requests from Sapling

Introduction

Sapling’s webhook allows you to receive notifications on specific events with details that are needed to keep your system up to date. We understand the importance of verifying the webhook to ensure it is genuine and the source is Sapling. In this article, we will walk you through how to generate a webhook token and validate requests from Sapling.

Please note: this article only covers how to authenticate webhook events triggered by Sapling. To learn more about creating webhooks and how to subscribe, please check our article on Subscription to Sapling Webhooks.

This article covers the following topics:

• Steps to regenerate a webhook token
• Steps to validate requests from Sapling
• How does Sapling generate the HTTP_X_SIGNATURE?

Steps to regenerate a Webhook Token

1. Go to the Webhook section and click on the revoke button to regenerate the webhook token on the Sapling side. See the screenshot below:
   
   
2. Once revoked, the webhook token will be generated and shown. Copy this token and save it for validating requests from Sapling.

Steps to validate requests from Sapling

Please implement the following logic in order to authenticate the request.

1. Check whether params include "test_request" or not. If yes, then ignore the request because it's just the testing request to authenticate whether the endpoint is accessible or not. Otherwise, move forward.
   Example:  params.include? "test_request"  #ruby's code
   
   
2. Fetch the data from the params as given below.
   Example: data = params["webhook_event"]
   
   
3. Get the signature that sapling sends in the headers using below example code:
   Example: request.headers["HTTP_X_SAPLING_SIGNATURE"] #ruby's code
   
   
4. Convert params into hash using the secret webhook token.
   

   Example: OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), webhook_token, data.to_json) #params should be in json
   
   

   Note: Get the webhook_token from the Webhook section in Sapling as mentioned above (Steps to regenerate Webhook Token).
   

5. If the hash returned from the above step matches with the one obtained in the third step, then the request is authorized, otherwise, it is not.

How does Sapling generate the HTTP_X_SAPLING_SIGNATURE?

Sapling uses OpenSSL to generate signatures for each request. It creates a hash using webhook_token and params(to be passed in request). Example ruby’s code below:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), token, request_body)

In the above example:

• 'sha256' is an algorithm to create a hash.
• A token is the webhook_token that is created on the Sapling side in the webhooks section.
• request_body is a hash of params that are to be passed in the request.