Secure webhooks

Overview

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.

Orum will send a Signature header on each webhook request we make to your server. 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.

Using the public key that is returned to by making a GET request to the webhooks/secret endpoint. You can verify the message has not been altered and that it is in fact coming from Orum.

Configure and Retrieve Your Public Key

Step 1: Initialize your public key

Orum manages a public-private RSA-2048 key pair that allows you to decrypt your digital signature. To initialize your public key, make a POST request to the webhooks/secret endpoint.

Step 2: Retrieve your public key

Once the key is initialized, you may retrieve it at any time by making a GET request to the webhooks/secret endpoint.

How to Validate the Signature

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 webhooks/secret endpoint
- The public key is RSA-2048
Verify that the decrypted digital signature from Orum and your recreated unencrypted plaintext digital signature match

The following code examples will allow you to verify your signature:

import base64
from Crypto.PublicKey import RSA
from Crypto.Hash import SHA256
from Crypto.Signature import pkcs1_15

# Python3 with pycryptodome

message_plus_created_at = req.body + created_at
orumSignature = req.headers['Signature']

encoded = message_plus_created_at.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")

// Node.js:
const messagePlusCreatedAt = JSON.stringify(req.body) + req.body.created_at
const signature = req.headers.signature;
const verify = crypto.createVerify('RSA-SHA256');
verify.update(messagePlusCreatedAt);
const isValid = verify.verify(publicKey, signature,'base64'); // boolean value

import java.nio.charset.StandardCharsets;
import java.security.*;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import org.json.JSONObject;

public class Main {
        public static void main(String[] args) throws Exception {
            String publicKeyStr = // public key returned by GET /webhooks/secret endpoint
            String body = // request body
            String sign = // Signature from request header
            JSONObject json = new JSONObject(body);
            String messagePlusCreatedAt = body + json.getString("created_at");

            byte[] publicKeyBytes = Base64.getDecoder().decode(publicKeyStr);
            X509EncodedKeySpec publicKeySpec = new X509EncodedKeySpec(publicKeyBytes);
            KeyFactory keyFactory = KeyFactory.getInstance("RSA");
            PublicKey publicKey = keyFactory.generatePublic(publicKeySpec);
            byte[] digest = messagePlusCreatedAt.getBytes(StandardCharsets.UTF_8);
            Signature sig = Signature.getInstance("SHA256withRSA");
            sig.initVerify(publicKey);
            sig.update(digest);
            boolean verifySign = sig.verify(Base64.getDecoder().decode(sign));
            System.out.println(verifySign);
        }
}