Webhook Signature Authentication
SuperPath can optionally sign each webhook by including a signature in each request’s header. This allows you to verify that the event requests were sent by SuperPath and not by an unauthorised third party.
In order to activate signature authentication make sure you select “Use web hook signature authentication” when creating a webhook event. You will be presented with a secret key that will be used to sign the request
By selecting this option, all requests made to your webhook endpoint will include a "Superpath-Signature" value in the header. An example payload could look like this:
POST /webhooktest HTTP/1.1
Host: api.superpath.io
Content-Length: 252
Content-Type: application/json
SuperPath-Signature: 1644921396,2029f1cbd5f55df4e19c5380e73492ff35be632a611160be435c69971c0606ab
User-Agent: axios/0.21.4
{"event":"points.create","dateSent":"2022-02-15T10:36:36.300Z", "dateSentOffset": 11, "data":{"tenantId": "abcdef", "id": "foettyQz714xBVi75gZ6", "firstName": "John", "lastName": "Lennon", "email": "john@beatles.com", "position": "Founder & CEO", "roleName": "Owner", "avatar": "https://res.cloudinary.com/superpath/image/upload/23423234234/john.jpg", "username": "john.lennon","employeeId": "2123234", "timezone": "Australia/Sydney", "pointsTotal": 427, "pointsSelfAssigned": 336, "pointsAssigned": 0, "status": "active", "isDeleted": false, "dateCreated": "2020-11-13T11:48:42.109Z", "dateCreatedOffset": 11, "dateLastModified": "2022-02-15T10:36:21.354Z", "dateLastModifiedOffset": 11, "userFullNameLastModified": "Jake Jackson","userIdLastModified": "foettyQz714xBVi75gZ6"}}
As you can see in the example above, the signature is included in the header:
SuperPath-Signature: 1644921396,2029f1cbd5f55df4e19c5380e73492ff35be632a611160be435c69971c0606ab
The signature is made up of 2 components that are comma separated. The first is the the timestamp when the signature has been created and the second component is the signature itself. The timestamp can be used to prevent replay attacks, by rejecting requests containing a timestamp which is too far in the past. The signature itself is generated using a hash-based message authentication code ( HMAC) with the SHA-256 algorithm.
The follow describes how to verify the signature in your endpoint:
Step 1: Extract timestamp and signature from the request header
Split the header value of "SuperPath-Signature", using the "," character as the separator, to retrieve an array of components. The array should contain 2 elements - the timestamp and signature.
Step 2: Calculate your own signature
Now using the secret key that you registered the webhook earlier, and the timestamp you obtained from Step 1 - you can now generate a signature (HMAC) with the SHA256 hash.
Step 3: Compare the received signature with your own
Compare the signature you have received in the request header with one you just generated. If they match, the request and payload come from a sender who knows your secret_key.
In order to activate signature authentication make sure you select “Use web hook signature authentication” when creating a webhook event. You will be presented with a secret key that will be used to sign the request
By selecting this option, all requests made to your webhook endpoint will include a "Superpath-Signature" value in the header. An example payload could look like this:
POST /webhooktest HTTP/1.1
Host: api.superpath.io
Content-Length: 252
Content-Type: application/json
SuperPath-Signature: 1644921396,2029f1cbd5f55df4e19c5380e73492ff35be632a611160be435c69971c0606ab
User-Agent: axios/0.21.4
{"event":"points.create","dateSent":"2022-02-15T10:36:36.300Z", "dateSentOffset": 11, "data":{"tenantId": "abcdef", "id": "foettyQz714xBVi75gZ6", "firstName": "John", "lastName": "Lennon", "email": "john@beatles.com", "position": "Founder & CEO", "roleName": "Owner", "avatar": "https://res.cloudinary.com/superpath/image/upload/23423234234/john.jpg", "username": "john.lennon","employeeId": "2123234", "timezone": "Australia/Sydney", "pointsTotal": 427, "pointsSelfAssigned": 336, "pointsAssigned": 0, "status": "active", "isDeleted": false, "dateCreated": "2020-11-13T11:48:42.109Z", "dateCreatedOffset": 11, "dateLastModified": "2022-02-15T10:36:21.354Z", "dateLastModifiedOffset": 11, "userFullNameLastModified": "Jake Jackson","userIdLastModified": "foettyQz714xBVi75gZ6"}}
Webhook request signature verification
As you can see in the example above, the signature is included in the header:
SuperPath-Signature: 1644921396,2029f1cbd5f55df4e19c5380e73492ff35be632a611160be435c69971c0606ab
The signature is made up of 2 components that are comma separated. The first is the the timestamp when the signature has been created and the second component is the signature itself. The timestamp can be used to prevent replay attacks, by rejecting requests containing a timestamp which is too far in the past. The signature itself is generated using a hash-based message authentication code ( HMAC) with the SHA-256 algorithm.
The follow describes how to verify the signature in your endpoint:
Step 1: Extract timestamp and signature from the request header
Split the header value of "SuperPath-Signature", using the "," character as the separator, to retrieve an array of components. The array should contain 2 elements - the timestamp and signature.
Step 2: Calculate your own signature
Now using the secret key that you registered the webhook earlier, and the timestamp you obtained from Step 1 - you can now generate a signature (HMAC) with the SHA256 hash.
Step 3: Compare the received signature with your own
Compare the signature you have received in the request header with one you just generated. If they match, the request and payload come from a sender who knows your secret_key.
Updated on: 13/02/2025
Thank you!