Authentication

Cuoral uses HMAC-SHA256 signatures to authenticate webhook requests and ensure that webhook events are coming from Cuoral.

Every webhook request includes a signature in the X-Cuoral-Webhook-Signature header.

Your webhook endpoint should verify this signature before processing the request.

Signature Header

The signature is provided in the following request header:

X-Cuoral-Webhook-Signature: <signature>

The signature is generated using:

• Algorithm: HMAC-SHA256

• Secret: Your organization's api_key

• Payload: The webhook request payload serialized as JSON with sorted keys

How Verification Works

When Cuoral sends a webhook, it:

1. Serializes the webhook payload as JSON with keys sorted alphabetically.

2. Uses your organization's api_key as the HMAC secret.

3. Generates an HMAC-SHA256 hash.

4. Sends the resulting hexadecimal signature in the X-Cuoral-Webhook-Signature header.

Your application should perform the same calculation and compare the generated signature with the value provided in the request header.

If the signatures match, the webhook can be considered authentic.

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signatureHeader, publicKey) {
  const payloadString = JSON.stringify(
    payload,
    Object.keys(payload).sort()
  );

  const expectedSignature = crypto
    .createHmac('sha256', publicKey)
    .update(payloadString)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signatureHeader)
  );
}

Python

import hmac
import hashlib
import json

def verify_webhook_signature(
    payload: dict,
    signature_header: str,
    public_key: str
) -> bool:
    payload_str = json.dumps(payload, sort_keys=True)

    expected_signature = hmac.new(
        public_key.encode("utf-8"),
        payload_str.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        expected_signature,
        signature_header
    )

Important: Verify the Raw Payload

For maximum reliability, webhook signature verification should be performed against the raw request body before your framework parses or transforms the JSON.

Re-serializing JSON can produce a different string due to differences in whitespace, escaping, or key ordering.

If your framework provides access to the raw request body, use it when calculating the HMAC.

Security Recommendations

• Always verify the X-Cuoral-Webhook-Signature header before processing a webhook.

• Keep your organization's api_key secret.

• Use HTTPS for your webhook endpoint.

• Use a constant-time comparison when comparing signatures.

• Return a successful HTTP status only after the webhook has been accepted and validated.