Verify Webhook Signatures

This page describes how to verify webhook signatures from Xtremepush when using the Signed Payload authentication type.

Webhook Signature Header

Xtremepush includes a HTTP header, X-Xtremepush-Signature, in every webhook request as shown in the example below:

X-Xtremepush-Signature:
t=1689343556,
v1=2c709b15aee216e2d7097cb57b7c5b422bea3fd938589dafab265506f7651011,
v1=874f7108d19848f35f3e70a4751ee2bfae164f4cc74259c405275c235963a141

This header contains two components:

1. Timestamp (t=...): Indicates when the webhook was sent. 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, your application should reject the payload.

   The signature verifies that the payload has not been tampered with in transit, but does not encrypt it, so the contents remain visible to anyone who intercepts the request.

2. Signature (v1=...): A signature generated using your unique signing secret. This secret is provided in the Webhook Secret Key field in your webhook integration settings. Xtremepush 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 the current version (v1).

Verify the webhook by generating your own signature using the same data and secret key. If your generated signature matches the one sent by Xtremepush, you can confirm that the payload has not been altered in transit and that it originated from Xtremepush.

📘

Handling Multiple Signatures

You can only have one active secret key at a time. When you generate a new key from the webhook integration settings, it immediately replaces the previous one.

Xtremepush will keep the previous secret active for up to 24 hours. During this time, Xtremepush generates a signature for both the new and the old secret, and your endpoint will receive both in the request header. This window is fixed and cannot be shortened.

Verify the Webhook Signature

Follow these steps to verify the webhook signatures.

1. Parse the X-Xtremepush-Signature header string.
   1. Split the header string by the comma character (,) to get a list of elements.
   2. Split each element by the equals character (=) to get its key and value.
   3. Store the value for the timestamp key (t) and all values for signature keys v1
2. Prepare the signed_payload string by concatenating the following:
   • The timestamp (str)
   • A period (.)
   • The JSON body of the request
3. Determine the expected signature by compute a HMAC with the SHA256 hash function.
   • key: Use your endpoint’s signing secret
   • Message: Use the signed_payload string you created in Step 2.
4. Compare Signatures and Validate
   1. Compare the signature (or signatures) in the header to the expected signature
   2. If a signatures matches, calculate the difference between the current timestamp and the received timestamp to decide if its within within your acceptable tolerance.
      To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.