Skip to main content

How to authenticate a webhook

Our Webhooks authentication process employs Signature Verification, which serves multiple purposes. Not only does it validate the payload and shield credentials, but it also safeguards against replay attacks. In essence, every webhook is endowed with a primary and a optional secondary secret. These secrets work with a cryptographic algorithm - HMAC - which uses the SHA256 algorithm to construct a cryptographic hash that serves as the webhook's unique signature in the headers.

To mitigate replay attacks, we include a timestamp in our process. This strategy is designed to minimise the risk of an attacker repeating an authenticated request, as it enables you to reject the webhook once the validity period of the request has expired.

The header of the webhook request should include:

eduframe-signature-v1:
    t = 1717747771,
    signature = 735b82e1e24769d02a39548f3bcc96ebd55f61b24a799fa98b786b53e56a1295,
    signature = d21d5148bc92ffa9334f2800720083c8073f68160c45f24e52061dccf76dd005

Where the first and second signature is made using the primary and secondary secret respectively. If there is no secondary secret it will only show the first ‘signature’.

Secrets​

⚠️️ Warning: Please be aware of potential risks involved with modifying and deleting webhook secrets.

View secrets​

Once a webhook has been created, a primary secret gets generated for it and can be viewed by clicking on Reveal button under the ‘Secrets’ column on the table.

Button to reveal secrets on webhook record Button to reveal secrets on webhook record

This opens a modal that allows you to view and configure your secrets:

Untitled Modal to configure webhook secrets

How to safely rotate secrets​

If you have a secondary secret you will then have the option to rotate your current secrets, meaning that the primary secret becomes the secondary secret, and generates a new primary secret.

Step-by-step:

  1. Click to rotate secrets → primary becomes secondary secret
  2. Change your current applications so that they use the new primary secret
  3. Delete the secondary secret once you know for certain that all your applications are using the new primary secret.