Webhook Signatures

CompetitionSuite can optionally sign the webhook events it sends to your endpoints by including a signature in each event’s CompSuite-Signature header. This allows you to verify that the events were sent by CompetitionSuite, not by a third party. You can verify signatures using the method described below.

Before you can verify signatures, you need to retrieve your endpoint’s secret from your Organization's Webhooks settings. Select an endpoint that you want to obtain the secret for, then click the Click to reveal button.

CompetitionSuite generates a unique secret key for each endpoint. If you use the same endpoint for both test and live API keys, note that the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one you want to verify signatures on. After this setup, CompetitionSuite starts to sign each webhook it sends to the endpoint.

Verifying signatures

The CompSuite-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.

CompSuite-Signature:
t=1655844460,
v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd,
v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

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

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

It is possible to have multiple signatures with the same scheme-secret pair. This can happen when you roll an endpoint’s secret from the Webhook Management page, and choose to keep the previous secret active for up to 24 hours. During this time, your endpoint has multiple active secrets and CompetitionSuite generates one signature for each secret.

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

Preventing replay attacks

A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, CompetitionSuite includes a timestamp in the CompSuite-Signature header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.

CompetitionSuite generates the timestamp and signature each time we send an event to your endpoint. If CompetitionSuite retries an event (for example, your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt.