Validating Webhooks

Once your server is configured to receive payloads, it will listen for any delivery that’s sent to the endpoint you configured. To ensure that your server only processes webhook deliveries that were sent by ProcessPlan 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 ProcessPlan and will help avoid man-in-the-middle attacks.

To do this, you need to:

1. Create a secret token for a webhook.

2. Store the token securely on your server.

3. Validate incoming webhook payloads against the token, to verify that they are coming from ProcessPlan and were not tampered with.

Creating a secret token

You can create a new webhook with a secret token, or you can add a secret token to an existing webhook. When creating a secret token, you should choose a random string of text with high entropy.

Securely storing the secret token

After creating a 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

ProcessPlan 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 “x-pp-signature-sha256” header.

In your code that handles webhook deliveries, you should calculate a hash using your secret token. Then, compare the hash that ProcessPlan 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:

• ProcessPlan uses an HMAC hex digest to compute the hash.

• The hash signature is generated using your webhook’s secret token and the payload contents.

• If your language and server implementation specifies a character encoding, ensure that you handle the payload as UTF-8. Webhook payloads can contain unicode characters.

Testing the webhook payload validation

You can use the following secret and payload values to verify that your implementation is correct:

• secret: “this is a secret key”

• payload: “Hello, World!”

If your implementation is correct, the signatures that you generate should match the following signature values:

• x-pp-signature-sha256: cbb972ab612c8a893c0ad886dee19ec41c1c1e8e00007d5bdd3c76ae175b0c21