Orum Portal

Secure webhooks

Verifying your digital signature

To verify your digital signature, complete the following steps:

  1. Initialize your public-private key pair
  2. Retrieve your public-private key pair
  3. 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:

  1. 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
  2. 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
  3. 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")