Verifying your digital signature
To verify your digital signature, complete the following steps:
- Initialize your public-private key pair
- Retrieve your public-private key pair
- Verify your digital signature
Step 1: Initialize your public-private key pair
Orum manages a public-private RSA-2048 key pair that allows you to decrypt your digital signature. To initialize your public-private key pair, make a POST request to the webhooks/secret
endpoint.
Step 2: Retrieve your public-private key pair
Once the key is initialized, you may retrieve it at any time by making a GET request to the webhooks/secret
endpoint.
Step 3: Verify your digital signature
Recreate the unencrypted signature and compare it to the decrypted signature from the webhook request, to ensure that the two match. To verify the digital signature, follow these steps:
- Recreate the unencrypted plaintext digital signature from the following information by taking a SHA256 hash of the concatenated string of:
- The webhook request body
- Plaintext timestamp of
created_at
field in the request body
- Decrypt the digital signature with your public key, this can be retrieved by making a GET request to https://api.orum.io/v1/webhooks/secret
- The public key is RSA-2048
- Verify that the decrypted digital signature from Orum and your recreated digital signature match
To verify that events were sent by Orum and not by a third party, Orum digitally signs our webhooks. This prevents data modification by third parties in the middle of the webhook transfer and ensures that the webhooks you receive have come from Orum.
The signature is made up of the following 2 components, which are then encrypted with an Orum-managed private key:
- The webhook request body
- The
created_at
timestamp in the request body
The two components are concatenated into the following formula for the digital signature:
SHA256(request.body + plaintext timestamp of created_at
)
We utilize a standardized signing library with PKCS1 v1.5 padding, the signature is base64 encoded. The following code examples will allow you to verify your signature:
// Node.js:
const signature = JSON.stringify(req.body) + req.body.created_at
const verify = crypto.createVerify('RSA-SHA256');
verify.update(signature);
const isValid = verify.verify(publicKey, req.get("Signature") ,'base64')); // boolean value
# Python3 with pycryptodome
signature = req.body + created_at
encoded = signature.encode()
result = SHA256.new(encoded)
try:
key = RSA.import_key(publicKeyString)
pkcs1_15.new(key).verify(
result, base64.b64decode(orumSignature)) # Will return an error if the signature does not match
print("verified!")
except:
print("Oops")