Webhooks Guide

public class WebhookPayload
{
    public string DuplicateId { get; set; }
    public DateTime DateIssued { get; set; }
    public DateTime DateFound { get; set; }
    public string SubscriptionExternalId { get; set; }
    public string JobExternalId { get; set; }
    public string JobExecutionExternalId { get; set; }
    public string TableName { get; set; }
    public string BaseRecordId { get; set; }
    public int ClusterSize { get; set; }
    public double MaxProbability { get; set; }
    public List<SubordinateRecord> Subordinates { get; set; }
    public string MergeOutputJson { get; set; }
}

public class SubordinateRecord
{
    public string RecordId { get; set; }
    public string RecordJson { get; set; }
    public double Probability { get; set; }
}

const crypto = require("crypto");

const MAX_TIMESTAMP_AGE_SECONDS = 300; // reject webhooks older than 5 minutes

module.exports = async function (context, req) {
    const secret = Buffer.from(process.env.WEBHOOK_SECRET, "base64");

    const signature = req.headers["x-webhook-signature"] || "";
    const timestamp = req.headers["x-webhook-timestamp"];

    // Reject stale requests (replay attack prevention)
    const webhookTime = parseInt(timestamp, 10);
    if (!webhookTime || Math.abs(Date.now() / 1000 - webhookTime) > MAX_TIMESTAMP_AGE_SECONDS) {
        context.res = { status: 401 };
        return;
    }

    // Use req.rawBody — the exact bytes received — NOT JSON.stringify(req.body).
    // Re-serialising the parsed object can change key order or whitespace and
    // will cause signature verification to fail.
    const rawBody = req.rawBody;
    const message = `${timestamp}.${rawBody}`;

    const expected = crypto
        .createHmac("sha256", secret)
        .update(message, "utf8")
        .digest("hex");

    const received = signature.replace("sha256=", "");

    const isValid = crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(received)
    );

    if (!isValid) {
        context.res = { status: 401 };
        return;
    }

    // ✅ Safe to parse and use the payload after verification
    const webhook = req.body;

    context.log(`Duplicate cluster detected: ${webhook.DuplicateId}`);
    context.log(`Cluster size: ${webhook.ClusterSize}, max probability: ${webhook.MaxProbability}`);
    for (const sub of webhook.Subordinates) {
        context.log(`  Subordinate: ${sub.RecordId} (probability: ${sub.Probability})`);
    }

    context.res = { status: 200 };
};

using System.Security.Cryptography;
using System.Text;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;

public class DeduplicaWebhook
{
    [Function("DeduplicaWebhook")]
    public static async Task<HttpResponseData> Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
    {
        var rawBody = await new StreamReader(req.Body).ReadToEndAsync();

        var timestamp = req.Headers.GetValues("X-Webhook-Timestamp").First();
        var signature = req.Headers.GetValues("X-Webhook-Signature").First();

        var secret = Convert.FromBase64String(
            Environment.GetEnvironmentVariable("WEBHOOK_SECRET")!
        );

        var message = $"{timestamp}.{rawBody}";

        using var hmac = new HMACSHA256(secret);
        var expected = Convert.ToHexString(
            hmac.ComputeHash(Encoding.UTF8.GetBytes(message))
        ).ToLowerInvariant();

        var received = signature.Replace("sha256=", "");

        var isValid = CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expected),
            Encoding.UTF8.GetBytes(received)
        );

        if (!isValid)
        {
            return req.CreateResponse(401);
        }

        // ✅ Safe to deserialize after verification
        var webhook = System.Text.Json.JsonSerializer.Deserialize<WebhookPayload>(rawBody)!;

        Console.WriteLine($"Duplicate cluster detected: {webhook.DuplicateId}");
        Console.WriteLine($"Cluster size: {webhook.ClusterSize}, max probability: {webhook.MaxProbability}");
        foreach (var sub in webhook.Subordinates)
        {
            Console.WriteLine($"  Subordinate: {sub.RecordId} (probability: {sub.Probability})");
        }

        return req.CreateResponse(200);
    }
}

import os
import hmac
import hashlib
import base64
import json
import logging
import time
import azure.functions as func

_MAX_TIMESTAMP_AGE_SECONDS = 300  # reject webhooks older than 5 minutes

app = func.FunctionApp()

@app.function_name(name="WebhookListener")
@app.route(route="webhook", auth_level=func.AuthLevel.ANONYMOUS, methods=["POST"])
def webhook_listener(req: func.HttpRequest) -> func.HttpResponse:
    signature_header = req.headers.get("x-webhook-signature", "")
    timestamp_header = req.headers.get("x-webhook-timestamp", "")

    # Reject stale requests (replay attack prevention)
    try:
        webhook_time = int(timestamp_header)
    except (ValueError, TypeError):
        return func.HttpResponse(status_code=401)
    if abs(time.time() - webhook_time) > _MAX_TIMESTAMP_AGE_SECONDS:
        return func.HttpResponse(status_code=401)

    raw_body = req.get_body().decode("utf-8")

    # WEBHOOK_SECRET is Base64-encoded; decode to raw bytes before use as HMAC key.
    secret = base64.b64decode(os.environ["WEBHOOK_SECRET"])
    message = f"{timestamp_header}.{raw_body}".encode("utf-8")
    expected = hmac.new(secret, message, hashlib.sha256).hexdigest()
    received = signature_header.replace("sha256=", "")

    if not hmac.compare_digest(expected, received):
        return func.HttpResponse(status_code=401)

    # ✅ Safe to parse after verification
    webhook = json.loads(raw_body)

    duplicate_id    = webhook.get("DuplicateId")
    cluster_size    = webhook.get("ClusterSize")
    max_probability = webhook.get("MaxProbability")
    base_record_id  = webhook.get("BaseRecordId")
    subordinates    = webhook.get("Subordinates") or []

    # MergeOutputJson is a JSON string — parse it as a second step.
    # If CLIENT_ENCRYPTION_KEY is set on the local agent it will be encrypted;
    # decrypt it with the same key before parsing.
    merge_output = None
    merge_output_json = webhook.get("MergeOutputJson")
    if merge_output_json:
        try:
            merge_output = json.loads(merge_output_json)
        except Exception:
            merge_output = merge_output_json  # encrypted — handle decryption here

    logging.info(f"Duplicate cluster: {duplicate_id}, size={cluster_size}, maxProb={max_probability}")
    logging.info(f"Base record: {base_record_id}")
    for i, sub in enumerate(subordinates):
        logging.info(f"  Subordinate[{i}] RecordId={sub.get('RecordId')} Probability={sub.get('Probability')}")
    if merge_output:
        logging.info(f"Merge output: {json.dumps(merge_output) if isinstance(merge_output, dict) else merge_output}")

    # TODO: implement your business logic here

    return func.HttpResponse(status_code=200)