Webhooks Signature Verification

Why Verify Signatures?

When your application receives a webhook from OCUS, it's crucial to verify that the request is genuinely from OCUS and has not been tampered with. Webhook signature verification ensures the integrity and authenticity of the payload, protecting your system from unauthorized or malicious requests.

How Signature Verification Works

OCUS signs each webhook request using a unique signature (the signature is different for each single notification) , which is included in the request header ocus-signature. To verify the authenticity of the request:

Retrieve the ocus-signature from the request headers.
Use the secret key that was provided when registering the webhook URL.
Recompute the HMAC SHA-256 hash using the response body.data and your secret key.
Compare the computed signature with the received ocus-signature. If they match, the request is valid.

Implementation Example

const crypto = require('crypto');

/**
 * Verify the OCUS webhook signature.
 *
 * @param {Object} req - Express request object
 * @param {string} secretKey - The secret key provided by Ocus
 * @returns {boolean} - True if the signature is valid, false otherwise
 */
function verifyOcusSignature(req, secretKey) {
    const receivedSignature = req.header('ocus-signature');
    if (!receivedSignature) {
        console.warn('Missing Ocus-Signature header');
        return false;
    }

    const message = JSON.stringify(req.body.data);
    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(message);
    const calculatedSignature = hmac.digest('hex');

    return calculatedSignature === receivedSignature;
}

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io/ioutil"
    "net/http"
)

// VerifyOcusSignature verifies the Ocus webhook signature.
func VerifyOcusSignature(r *http.Request, secretKey string) bool {
    receivedSignature := r.Header.Get("Ocus-Signature")
    if receivedSignature == "" {
        fmt.Println("Missing Ocus-Signature header")
        return false
    }

    body, err := ioutil.ReadAll(r.Body)
    if err != nil {
        fmt.Println("Error reading request body:", err)
        return false
    }
    defer r.Body.Close()

    h := hmac.New(sha256.New, []byte(secretKey))
    h.Write(body)
    calculatedSignature := hex.EncodeToString(h.Sum(nil))

    return calculatedSignature == receivedSignature
}

Error Handling and Security Considerations

Ensure the Secret Key is Secure: Never expose your secret key in client-side code or logs.
Reject Requests with Missing or Invalid Signatures: Log these attempts for monitoring.

By following these steps, you can ensure that only legitimate webhook requests from OCUS are processed by your application.