If you want to verify that callbacks come from Sightengine and not from a third-party, Sightengine can sign the callbacks it sends to your endpoint. Signatures are done through a Sightengine-Signature header.
Sightengine generates signatures using an HMAC code with SHA-256.
The Sightengine-Signature header included in each signed callback contains a timestamp and a signature. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Currently, the only valid live signature scheme is v1. Here is an example:
Sightengine-Signature:t=1492774577,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Step 1: Retrieve your endpoint's secret from your dashboard.
Go to the callbacks page on your dashboard to define your callback url (if you haven't already) and retrieve the corresponding signing secret. The signing secret is a string that starts with casec_.
Step 2: 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 3: Determine the expected signature
Concatenate the following strings into a single string that we will name to_be_signedCompute the HMAC of the to_be_signed string using SHA256 as hash function and using the endpoint's signing secret as the key.
Step 4: Compare the signatures
Compare the signature in the header with the expected signature, and check that they match. We recommend that you use a constant-time string comparison to prevent timing attacks.
You should also check that the difference between the current timestamp and the received timestamp is within your tolerance range.
Was this page helpful?