Skip to main content

Webhook Signatures

Overview​

Talroo will sign the webhook events it sends to your endpoints by including a signature in each event’s x-talroo-signature header. This allows you to verify that the events were sent by Talroo, not by a third party. Additionally, webhook signature verification can help prevent replay attacks. Replay attacks occur when an attacker intercepts a valid payload and its signature and then re-transmits them.

Directions to verify a Talroo webhook signature can be found below.

Webhook Signature Verification​

The x-talroo-signature header included in each signed event contains a timestamp 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

In the x-talroo-signature example below, newlines have been added for clarity, but a real x-talroo-signature header is on a single line.

x-talroo-signature:
t=1685045143,
v1=7d0sd2b25451b9b21bf9dc27b401c7671accf8cc8000c87b1c45b59991b7f9d9

Talroo generates signatures using a hash-based message authentication code HMAC with SHA-256. To prevent downgrade attacks, 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. 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 you provided 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 each of the received signatures.