# Webhook Signature

Tillhub signs the webhook events it sends to your endpoints by including a signature in each event’s Tillhub-Signature header. By verifying this signature, you can make sure this request has been sent to your endpoint by Tillhub.

# Verifying signature

The Tillhub-Signature header included in each event contains a timestamp and a signature. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid live signature scheme is v1.

Tillhub-Signature:
t=1669124083188,
v1=tPn4jcqptzmComnm4UxlSLAfxf+5/730jqwNSu4Bjdk=
1
2
3

Note that newlines have been added for clarity, but a real Tillhub-Signature header is on a single line.

Tillhub generates signature using a hash-based message authentication code (HMAC) with SHA-256.

# Step 1: Extract the 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. You can discard all other elements.

# Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating:

  • The timestamp (as a string)
  • The character .
  • The actual JSON payload (that is, the request body)

# Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

# 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.

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

# Code Example

In this Node.js/Typescript example the signature is being validated using crypto Module