Link Search Menu Expand Document

Check the webhook signatures

Verify the events that Tilled sends to your webhook endpoints.

Tilled signs the webhook events it sends to your endpoints by including a siganture in each event’s tilled-signature header. This allows you to verify that the events were sent by Tilled, not by a third party. You can verify signatures manually using the information below.

Before you can verify signatures, you need to retrieve your enddpoint’s secret which is only available at the time of creation. If you create this webhook endpoint via the API then the response will contain a secret property, and if you create it via the Tilled Console the secret will be displayed once after creation.

Tilled generates a unique secret key for each endpoint. If you use multiple endpoints, you must obtain a secret for each one you want to verify signatures on. After this setup, Tilled starts to sign each webhook it sends to the endpoint.

Verifying signatures

The tilled-signature header included in each signed event contains a timestamp (UTC) and one or more signatures. 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.


Note: the newlines have been added for clarity, but a real tilled-signature header is on a single line.

Tilled generates signatures using a hash-based message authentication code (HMAC) with SHA-256. You should ignore all schemes that are not v1.

Step 1: Extract the timestamp and signatures 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 signed_payload string

The signed_payload string is created by concatenating:

  • The timestamp (as a string)
  • The character .
  • The actual JSON payload (i.e., 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 (or signatures) 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 each of the received signatures.

Copyright © 2022 Tilled