Verifying Webhook Data

Whenever you receive a webhook event from Gradual, it includes a signature you can use to verify that the data came from Gradual and was not altered in transit.

Below is a step-by-step guide on verifying the webhook data using the secret key.

Getting Your Secret Key

Verifying the Signature

It should look something like this: t=1492774577,v0=abcd1234

This is formed by concatenating:

- The timestamp (as a string)

- The character '.'

- The actual JSON payload (i.e., the request body)

- Use the HMAC-SHA256 algorithm. In most programming languages, you would use a function like createHmac .

- Use your API secret key as the key.

- Use the signed_payload string as the message.

If you just rotated the secret recently, we will create signatures with the new and old secrets.

The signature header value looks like this:

t=1492774577,v0=abcd1234,v0=abcd5678 . ‘abcd1234’ is generated with the new secret, and ‘abcd5678’ is generated with the old one.

The old secret will be expired after 48 hours, and only the new secret’s signature will be included.

Example Python method to verify the signature:

import hmac
import hashlib
def verify_signature(signature_header_value, payload, secret):
# Split the header value into components
parts = signature_header_value.split(',')
# Extract timestamp and signatures
timestamp = parts[0].split('=')[1]
signatures = [part.split('=')[1] for part in parts[1:]]
# Generate HMAC for the secret
timed_message = f'{timestamp}.{payload}'
hmac_obj = hmac.new(secret.encode(), timed_message.encode(), hashlib.sha256)
generated_signature = hmac_obj.hexdigest()
# Verify if any signature matches
return any(signature == generated_signature for signature in signatures)

This guide covers the basics of signature verification. The exact way to perform these steps may vary depending on the programming language and libraries you're using. If you encounter issues verifying the signature or have questions, please contact us for support.