Changing webhook signatures

When configured, the signature on a webhook notification can be used by the recipient to verify that the notification came from Helix ALM. A webhook signature is generated by taking information specific to an individual webhook notification, hashing it with a specific algorithm and shared secret key, and providing the result along with the notification. When the recipient gets the notification it can re-generate the signature (using the same information, algorithm, and shared secret key), and compare the result against the one provided by Helix ALM.

Updating your signature

Signatures may need to be updated periodically, either as part of your organization following good security practices or due to concerns a signature’s key may have been compromised. However, changing signature configuration requires both Helix ALM and the recipient to be updated at the same time to prevent webhook notifications from being rejected, which may not always be feasible.

To accommodate this scenario, when changing a signature configuration, you may optionally choose to retain the prior signature configuration for up to 24 hours. When choosing this option:

  • Helix ALM uses the current configuration to create a “primary” signature for webhook notifications sent to this recipient.
  • Helix ALM uses the prior configuration to create a “secondary” signature for webhook notifications sent to this recipient.
  • If the primary signature configuration is changed while a secondary signature configuration already exists, the primary signature is replaced without changing the secondary signature configuration.
  • If you need to remove the secondary signature before the 24 hour grace period expires, use the Revoke command from the Security section of the Add Webhook Recipient dialog.

To take advantage of this functionality, the recipient needs to support checking for and verifying secondary signatures on webhook notifications in the event the primary signature verification fails.

1. Click Change from the Security section of the Add Webhook Recipient dialog.

The Change Webhook Signature dialog box opens.

2. Select the verification method from the Verification method menu.

  • Select None if you do not want to define a signature for verification.
  • Select HMAC SHA-256 to use a keyed hash algorithm constructed from the SHA-256 hash function and used as a Hash-based Message Authentication Code (HMAC).
  • Select HMAC SHA-512 to use a keyed hash algorithm constructed from the SHA-512 hash function and used as a HMAC.

3. Enter the Shared secret key. Any text in this field is obscured for added security. The secret key must be from 32 to 64 characters long.

4. Click Generate to generate a random secret key. This key is copied to the clipboard so you can easily paste it into the system that receives the webhook notifications from Helix ALM.

5. Click Save to save the verification signature. Upon saving the signature, Helix ALM performs the following verification steps on the signature:

  • If the text in the Shared secret key field does not meet the character length restrictions, an error message appears when you try to save the verification signature.

  • If the recipient does not already have an active secondary signature configuration, you have the option of making the previous configuration into a secondary signature for webhook notifications.