Webhooks Introduction

import hmac
import hashlib
import json

def generate_sha256_signature(payload: dict, secret: str) -> str:
    """
    Generate signature SHA256 using HMAC hex digest.

    Parameters:
    payload (dict): The payload of the webhook request.
    secret (str): The shared secret key.

    Returns:
    str: The generated HMAC-SHA256 signature, prefixed with "sha256=".
    """
    # Ensure the payload is dumped as a compact JSON string, matching how Ripio generates it.
    # Ripio's example uses json.dumps(payload) which might include spaces.
    # For consistency, ensure your server and Ripio use the exact same serialization.
    # If Ripio sends compact JSON (no spaces after separators), use:
    # payload_bytes = json.dumps(payload, separators=(',', ':')).encode("utf-8")
    # Based on the PDF's example, it seems to be standard json.dumps():
    payload_bytes = json.dumps(payload).encode("utf-8")

    hash_object = hmac.new(
        secret.encode("utf-8"),
        msg=payload_bytes,
        digestmod=hashlib.sha256
    )
    signature = "sha256=" + hash_object.hexdigest()
    return signature

def verify_signature(payload: dict, secret: str, signature_header: str) -> bool:
    """
    Verify that the payload was sent from a trusted source by validating SHA256 signature.

    Parameters:
    payload (dict): The payload of the webhook request.
    secret (str): The shared secret key.
    signature_header (str): The signature received in the `Http-X-Wh-Signature-256` header.

    Returns:
    bool: True if the signature is valid, False otherwise.
    """
    expected_signature = generate_sha256_signature(payload, secret)
    return hmac.compare_digest(expected_signature, signature_header)

# Example Usage (within a web framework like Flask)
# from flask import request, abort
#
# shared_secret = "your_shared_secret" # Replace with your actual shared secret
#
# @app.route('/webhook-receiver', methods=['POST'])
# def webhook_receiver():
#     received_signature = request.headers.get('Http-X-Wh-Signature-256')
#     payload = request.json # Assumes the payload is JSON
#
#     if not received_signature or not payload:
#         abort(400, 'Missing signature or payload')
#
#     if verify_signature(payload, shared_secret, received_signature):
#         # Process the valid webhook payload
#         print("Signature is valid. Processing payload:", payload)
#         # Add your business logic here
#         return "Webhook received and validated.", 200
#     else:
#         # Invalid signature
#         print("Invalid signature.")
#         abort(403, 'Invalid signature. Reject the request.')

from flask import Flask, request, abort
import hmac
import hashlib
import json

app = Flask(__name__)

# Replace with your actual shared secret provided by Ripio
SHARED_SECRET = "your_ripio_shared_secret"

def generate_expected_signature(payload_bytes: bytes, secret: str) -> str:
    hash_object = hmac.new(
        secret.encode("utf-8"),
        msg=payload_bytes,
        digestmod=hashlib.sha256
    )
    return "sha256=" + hash_object.hexdigest()

@app.route('/ripio-webhook-handler', methods=['POST'])
def ripio_webhook_handler():
    received_signature = request.headers.get('Http-X-Wh-Signature-256')
    
    # Get raw body bytes for signature verification
    raw_payload_bytes = request.get_data() # Important: use raw bytes

    if not received_signature:
        print("Error: Missing Http-X-Wh-Signature-256 header")
        abort(400, 'Missing signature header')

    if not raw_payload_bytes:
        print("Error: Missing payload")
        abort(400, 'Missing payload')

    expected_signature = generate_expected_signature(raw_payload_bytes, SHARED_SECRET)

    if not hmac.compare_digest(expected_signature, received_signature):
        print(f"Error: Invalid signature. Expected: {expected_signature}, Received: {received_signature}")
        abort(403, 'Invalid signature')

    # If signature is valid, parse the JSON payload for processing
    try:
        payload_json = json.loads(raw_payload_bytes.decode('utf-8'))
    except json.JSONDecodeError:
        print("Error: Could not decode JSON payload")
        abort(400, 'Invalid JSON payload')

    print("Webhook received and signature validated!")
    print("Event Type:", payload_json.get("eventType"))
    print("Payload:", payload_json)

    # TODO: Add your asynchronous business logic here
    # (e.g., add to a queue for processing)

    return "Webhook processed successfully", 200

if __name__ == '__main__':
    # For development only. Use a proper WSGI server in production.
    app.run(port=5000, debug=True)

const express = require('express');
const crypto = require('crypto');
const bodyParser = require('body-parser');

const app = express();
const port = 3000;

// Replace with your actual shared secret provided by Ripio
const SHARED_SECRET = 'your_ripio_shared_secret';

// Middleware to get raw body for signature verification
// Important: This needs to be before express.json() if you also want to use it
app.use(bodyParser.json({
  verify: (req, res, buf, encoding) => {
    if (buf && buf.length) {
      req.rawBody = buf.toString(encoding || 'utf8');
    }
  }
}));

app.post('/ripio-webhook-handler', (req, res) => {
  const receivedSignature = req.headers['http-x-wh-signature-256']; // Headers are lowercased by some servers/frameworks

  if (!receivedSignature) {
    console.error('Error: Missing Http-X-Wh-Signature-256 header');
    return res.status(400).send('Missing signature header');
  }

  if (!req.rawBody) {
    console.error('Error: Missing raw body payload');
    return res.status(400).send('Missing payload');
  }

  const hmac = crypto.createHmac('sha256', SHARED_SECRET);
  const expectedSignature = 'sha256=' + hmac.update(req.rawBody).digest('hex');

  // Use crypto.timingSafeEqual for comparing signatures to prevent timing attacks
  const signaturesMatch = crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'utf8'),
    Buffer.from(receivedSignature, 'utf8')
  );

  if (!signaturesMatch) {
    console.error(`Error: Invalid signature. Expected: ${expectedSignature}, Received: ${receivedSignature}`);
    return res.status(403).send('Invalid signature');
  }

  // Signature is valid, req.body contains the parsed JSON payload (due to bodyParser.json())
  const payload = req.body; 
  console.log('Webhook received and signature validated!');
  console.log('Event Type:', payload.eventType);
  console.log('Payload:', payload);

  // TODO: Add your asynchronous business logic here
  // (e.g., add to a message queue for processing)

  res.status(200).send('Webhook processed successfully');
});

app.listen(port, () => {
  console.log(`Webhook handler listening at http://localhost:${port}/ripio-webhook-handler`);
});