Webhook Security

WHCC signs every webhook request it sends to your endpoint by including a WHCC-Signature header.

If you have an Editor API integration, WHCC provides an endpoint to make signature validation simple and straightforward.

Signature verification

The WHCC-Signature headed included in each webhook event contains a timestamp and one or more signatures. The timestamp is prefixed by t= and each signature is prefixed by a version v, followed by an integer. Currently, the only valid version is v1.


You can see a sample signature below:

1
2
3
   WHCC-Signature:
   t=1591735205,
   v1=307D88AF1425DC58552C1A6EDFB4C95E3E989F5B878CAFFEFFA6D581578DC82A

Newlines have been added to the above header for readability purposes only, an actual WHCC-Signature will be on a single line.

Step 1: Extract timestamp and signature from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures). You can discard all other elements.

Step 2: Prepare the payload

The string to be hashed is assembled by concatenating:

  1. The timestamp as a string

  2. The character .

  3. The JSON payload as a string (the request body)

Step 3: Compute the expected signature

Compute an HMAC with the SHA256 hash function. The key will be your consumer secret and the message is the assembled string from the previous step.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

Preventing common attacks

Replay Attacks

To protect against replay attacks, where an attacker intercepts a valid payload and its signature, then re-transmits them, you can set a tolerance for the timestamp included in the signature.

Downgrade Attacks

To protect against downgrade attacks, you should ignore all signatures that are not v1

Timing attacks

To protect against timing attacks, be sure to use a constant-time string comparison to compare the expected signature to the received signature.

Back to Top 👆
Get in Touch

Interested in integrating with WHCC? Tell us more about what you’re looking for and we’ll be in touch.