DEV Community: Doaa H Alshawwa

Accessible Generosity Translator – Bridging Local Aid Requests and Global Donors

Doaa H Alshawwa — Mon, 07 Sep 2026 07:05:56 +0000

This is a submission for Weekend Challenge: Generosity Edition

What I Built

Accessible Generosity Translator is a lightweight Java CLI application that bridges local grassroots initiatives with global support platforms.

In conflict zones and under-resourced regions—such as Gaza and Palestine—small volunteer groups often post urgent aid requests on social media in local dialects. These informal requests lack the language fluency and formal structure required by international donor networks.

This tool takes raw, unstructured local aid requests (e.g., informal Arabic notes) and leverages Google's Gemini API to instantly transform them into transparent, professional, English-language campaign briefs formatted in Markdown.

Demo

Sample Raw Input:

"نحن مجموعة متطوعين في خانيونس نحتاج بشكل عاجل 50 طرد غذائي و20 بطانية للأسر النازحة، التكلفة الإجمالية نحو 1500 دولار."

Generated Campaign Brief Output:

Emergency Food & Shelter Relief in Khan Younis

Urgent Need & Context
A local volunteer team in Khan Younis is requesting immediate assistance to provide basic food and shelter items for displaced families facing critical shortages.

Item	Quantity	Estimated Cost (USD)
Food Packages	50	$1,100
Blankets	20	$400
Total		$1,500

Verification & Transparency Note
Direct grassroots request. Donors are advised to verify local delivery channels and request itemized purchase receipts upon distribution.

Code

View Full Source Code on GitHub Repository

// Core API Integration using Java 11+ Native HttpClient
private static String generateEnglishCampaign(String rawStory) throws Exception {
    String systemInstruction = "You are an assistant for non-profit initiatives. "
            + "Translate and structure the following local initiative input into a transparent, professional English fundraising report. "
            + "Output MUST be formatted in Markdown with these headings: "
            + "1. Initiative Title, 2. Urgent Need & Context, 3. Breakdown of Items Needed (in a table), 4. Verification & Transparency Note. "
            + "Input story: " + rawStory.replace(""", "\"");

    String jsonPayload = "{"
            + ""contents": [{"
            + "  "parts": [{"text": "" + systemInstruction + ""}]"
            + "}]"
            + "}";

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(GEMINI_URL))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    return parseResponse(response.body());
}

How I Built It

Java 11+ HttpClient: Built completely dependency-free using Java's native HTTP features to ensure low memory footprint, instant execution, and portable deployment.
Google Gemini 1.5 Flash: Used to parse raw contextual Arabic, extract pricing and quantity figures, translate intent accurately, and enforce structured Markdown tables.
Prompt Engineering: Configured strict system instructions to guarantee every output includes a transparency disclaimer and itemized budgeting.

Prize Categories

Best Use of Google AI: The application relies entirely on Google Gemini 1.5 Flash to perform multilingual context extraction, financial structuring, and fundraising report generation in real time.

Gray to Red #1 (Study Journey): Replacing Heavy Array Slicing with (i + 1) % n

Doaa H Alshawwa — Wed, 02 Sep 2026 09:52:40 +0000

Problem Overview: Problem J - Sorted After Rotation

During Hebron Code Jam 2026, I faced Problem J: Sorted After Rotation.

You are given an array a of n distinct integers. You can cyclically shift the entire array to the left by k positions. The goal is to determine if it is possible to make the array strictly increasing after some number of cyclic shifts.

Input: t test cases, each containing n elements a_1, a_2, \dots, a_n.
Output: "YES" if a valid cyclic shift exists, "NO" otherwise.

What I Learned From This Problem

Circular Indexing (i + 1) % n: Instead of creating sublists or shifting array elements, (i + 1) % n links the last element back to index 0. This eliminates boundary checks and array slicing.
Property of Rotated Sorted Arrays: A strictly increasing array that is cyclically shifted has at most 1 drop where a[i] > a[i+1] across its circular boundary.
- 0 drops: Already sorted.
- 1 drop: Valid rotated sorted array.
- >1 drops: Impossible to fix with rotations.
Avoid Unnecessary Collections: Storing all outputs in an ArrayList<String> before printing creates massive memory overhead and triggers Garbage Collection pauses. Printing directly per testcase is much cleaner.
Fixing Algorithmic Complexity First: Going from O(N log N) to O(N) time complexity allowed Scanner to pass within generous time limits.

Original Implementation (Memory Heavy + `O(N \log N)`)

My first attempt manually split the array, created multiple ArrayList instances, and sorted them to compare equality:

package j;
import java.util.*;

public class J {

    public static void main(String[] args) {
        Scanner scan = new Scanner(System.in);
        int n = scan.nextInt();
        ArrayList<String> arr = new ArrayList<>();
        for (int i = 0; i < n; i++) {
            int min = 1;
            int ind = 0;
            int len = scan.nextInt();
            ArrayList<Integer> arr2 = new ArrayList<>();
            for (int j = 0; j < len; j++) {
                arr2.add(scan.nextInt());
                if (arr2.get(j) <= min) {
                    min = arr2.get(j);
                    ind = j; 
                }
            }

            List<Integer> arr5 = arr2.subList(ind, len);
            List<Integer> arr7 = new ArrayList<>();
            List<Integer> arr6 = arr2.subList(0, ind);

            for (int k = 0; k < arr5.size(); k++) {
                arr7.add(arr5.get(k));
            }

            for (int k = 0; k < arr6.size(); k++) {
                arr7.add(arr6.get(k));
            }

            Collections.sort(arr2);
            if (arr2.equals(arr7)){arr.add("YES");}
            else {arr.add("NO");}
        }

        for (int i = 0; i<arr.size() ; i++){System.out.println(arr.get(i));}
    }
}

Final Optimized Implementation ($O(N)$ Time)

By replacing array slicing with circular drop counts and primitive arrays, the code becomes concise and fast:

import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        Scanner scan = new Scanner(System.in);

        if (!scan.hasNextInt()) return;
        int t = scan.nextInt();

        while (t-- > 0) {
            int n = scan.nextInt();
            int[] a = new int[n];

            for (int i = 0; i < n; i++) {
                a[i] = scan.nextInt();
            }

            int drops = 0;
            for (int i = 0; i < n; i++) {
                if (a[i] > a[(i + 1) % n]) {
                    drops++;
                }
            }

            if (drops <= 1) {
                System.out.println("YES");
            } else {
                System.out.println("NO");
            }
        }
    }
}

Core Comparison

Aspect	Original Implementation	Final Optimized Implementation
Logic / Strategy	Physical rotation via `subList()`, merging lists, and calling `Collections.sort()`.	Single linear pass inspecting adjacent elements circularly using `(i + 1) % n`.
Time Complexity	`O(N log N)` due to sorting per test case.	`O(N)` linear time per test case.
Memory Overhead	High memory strain from instantiating multiple `ArrayList` and `subList` objects per testcase.	Minimal overhead using primitive `int[]` array reuse and direct output.
Logical Bug	Hardcoding `int min = 1` failed when array elements were strictly larger than 1 (e.g., `10^9`).	Removed minimum-element searching entirely; decision is purely based on drop count.

Checking 800M Leaked Passwords in 2MB of RAM with Bloom Filters

Doaa H Alshawwa — Tue, 25 Aug 2026 10:01:25 +0000

When users register or change their passwords, security guidelines (like NIST SP 800-63B) recommend checking their chosen password against a database of known breached passwords.

Data feeds like HaveIBeenPwned contain over 800 million leaked password hashes.

Storing 800 million SHA-1 hashes (20 bytes each) in a standard Hash Map or Redis set requires at least 16 GB of RAM. Performing a SQL database query on every password change adds unnecessary latency to your authentication pipeline.

In this post, we’ll explore how to use a probabilistic data structure—the Bloom Filter—to check hundreds of millions of leaked passwords in under 2 MB of RAM with constant O(k) lookup time.

The Problem: Why Hash Sets Don't Scale in Memory

A standard Hash Set gives you O(1) lookups with zero error rate. However, memory usage grows linearly with the number of inserted items N:

800,000,000 raw hashes pprox 16 GB RAM (excluding object overhead).
Adding metadata, pointers, and hash table buckets pushes actual memory consumption closer to 30+ GB.

For microservices, serverless functions, or API gateways, holding 30 GB of data in memory just for a password check is completely impractical.

The Algorithmic Fix: Bloom Filters

A Bloom Filter is a space-efficient probabilistic data structure. Instead of storing the actual keys, it uses a Bit Array of size m and k independent hash functions.

The Two Golden Rules of Bloom Filters

No False Negatives: If the filter returns false ("Not in Set"), the password is 100% guaranteed to be safe and uncompromised.
Controlled False Positives: If the filter returns true ("In Set"), the password is probably leaked. You can either reject it immediately or trigger a secondary check against a disk database.

Because we never store the actual string or hash—only single bit flips—we trade a tiny fraction of accuracy for orders-of-magnitude memory reduction.

The Math Behind Bloom Filters

The probability of a false positive p depends on three variables:

n: Number of items inserted (e.g., 10,000,000 passwords)
m: Size of the bit array (in bits)
k: Number of hash functions

To achieve a false positive probability p, the optimal number of hash functions k is calculated as:

k = r a c m n ln (2)

And the required bit array size m for a desired false positive rate p is:

m = - r a c n ln (p) (ln 2)^{2}

For 10 million passwords with a 1% false positive rate (p = 0.01), we only need roughly 95 million bits (~11.4 MB of memory).

Double Hashing: Efficient Hash Generation

Running k separate hash algorithms (like SHA256, MD5, FNV, etc.) per password would be CPU intensive. Instead, competitive programming and production systems use Kirsch-Mitzenmacher Double Hashing.

Using just two 32-bit hashes (h_1 and h_2), we can generate k distinct hash indices using the formula:

g_{i} (x) = (h_{1} (x) + i \cdot h_{2} (x)) (mod m)

Building a Password Guard in Node.js

Here is a complete Node.js implementation of a Bloom Filter using double hashing:

const crypto = require('crypto');

class PasswordBloomFilter {
  /**
   * @param {number} expectedItems (n) - Expected number of leaked passwords
   * @param {number} falsePositiveRate (p) - Desired error rate (e.g. 0.01 for 1%)
   */
  constructor(expectedItems = 10000000, falsePositiveRate = 0.01) {
    this.n = expectedItems;
    this.p = falsePositiveRate;

    // Calculate optimal m (bits) and optimal k (hashes)
    this.m = Math.ceil(-1 * (this.n * Math.log(this.p)) / (Math.log(2) ** 2));
    this.k = Math.round((this.m / this.n) * Math.log(2));

    // Allocate bit array (Buffer in Node.js)
    const byteSize = Math.ceil(this.m / 8);
    this.bitArray = Buffer.alloc(byteSize);
  }

  // Generate h1 and h2 using 64-bit split from SHA-256
  _getHashPair(item) {
    const hash = crypto.createHash('sha256').update(item).digest();
    const h1 = hash.readUInt32BE(0);
    const h2 = hash.readUInt32BE(4);
    return { h1, h2 };
  }

  // Set bit at index in buffer
  _setBit(index) {
    const byteIndex = Math.floor(index / 8);
    const bitOffset = index % 8;
    this.bitArray[byteIndex] |= (1 << bitOffset);
  }

  // Check bit at index in buffer
  _getBit(index) {
    const byteIndex = Math.floor(index / 8);
    const bitOffset = index % 8;
    return (this.bitArray[byteIndex] & (1 << bitOffset)) !== 0;
  }

  // Insert a known leaked password into the filter
  add(password) {
    const { h1, h2 } = this._getHashPair(password);
    for (let i = 0; i < this.k; i++) {
      const bitIndex = Math.abs((h1 + i * h2) % this.m);
      this._setBit(bitIndex);
    }
  }

  // Check if a user's chosen password might be leaked
  isLeaked(password) {
    const { h1, h2 } = this._getHashPair(password);
    for (let i = 0; i < this.k; i++) {
      const bitIndex = Math.abs((h1 + i * h2) % this.m);
      if (!this._getBit(bitIndex)) {
        return false; // Guaranteed NOT leaked!
      }
    }
    return true; // Probably leaked (triggers password change warning)
  }
}

// Example Express Middleware Usage
const filter = new PasswordBloomFilter(1000000, 0.01); // 1M passwords, 1% FP rate

// Pre-load breached hashes into memory on server startup
filter.add("Password123!");
filter.add("12345678");
filter.add("admin@2024");

function validatePasswordMiddleware(req, res, next) {
  const { password } = req.body;

  if (filter.isLeaked(password)) {
    return res.status(400).json({
      error: "Weak Password",
      message: "This password appears in known data breaches. Please choose a safer one."
    });
  }

  next();
}

Key Engineering Takeaways

Massive Memory Compression: Replaced tens of gigabytes of raw hash storage with a lightweight bit buffer.
Instant O(k) Evaluation: Looking up a password requires computing k hash offsets in memory without hitches or network calls.
Ideal First-Line Defense: Because there are zero false negatives, safe passwords bypass heavy database queries instantly.

Combining bitwise operations, probabilistic theory, and double hashing creates a high-performance guardrail for modern authentication systems.

Blocking Millions of Malicious IPs in O(32) Time with Bitwise Tries

Doaa H Alshawwa — Mon, 24 Aug 2026 09:53:40 +0000

If you're running an API gateway or FinTech service, blocking malicious traffic is a baseline requirement. Whether it's credential stuffing, scraping, or botnet attacks, your first line of defense is usually an IP blacklist.

Exact IP matching is easy. But attackers rarely use a single static IP. They rotate across entire subnets (CIDR blocks like 192.168.1.0/24).

If you try to match incoming requests against thousands of CIDR blocks, standard data structures break down. In this post, we’ll look at why linear arrays and Hash Maps fail at CIDR filtering, and how to build a Bitwise Trie that evaluates subnets in fixed sub-millisecond time.

The Problem: Why Hash Maps Fail at CIDR Matching

For exact IP lookup, a Hash Map gives you O(1) time complexity. You hash 192.168.1.5, look up the key, and get an immediate answer.

However, CIDR notation represents a range of IP addresses:

192.168.1.0/24 covers all 256 IPs from 192.168.1.0 to 192.168.1.255.

A Hash Map cannot perform prefix matching or range evaluation out of the box. To check if an incoming IP belongs to a blacklisted subnet using traditional methods, you either have to:

Iterate over an array of CIDR blocks (O(N) time complexity): If you have 50,000 blacklisted subnets, every single HTTP request performs up to 50,000 bitwise masking operations.
Expand subnets into individual IPs in a Hash Map (O(M) space complexity): Expanding a /16 subnet adds 65,536 entries to memory. Expanding multiple /8 subnets will crash your server process with out-of-memory errors.

The Algorithmic Fix: Bitwise Trie (Prefix Tree)

In competitive programming, Tries are commonly used for word dictionary lookups and prefix matching. Because an IPv4 address is simply a 32-bit unsigned integer, we can treat its binary representation as a string of 32 characters (0s and 1s).

A Bitwise Trie for IPv4 has two key properties:

Binary Nodes: Every node has at most two children: 0 (left) and 1 (right).
Fixed Depth: The maximum depth of the tree is strictly 32 levels (one for each bit of an IPv4 address).

How CIDR Insertion Works

Inserting a CIDR block like 192.168.1.0/24 means converting 192.168.1.0 into binary and walking down the Trie for only the first 24 bits (the network prefix). At the 24th bit node, we set isBlocked = true.

How IP Lookup Works

When an incoming request arrives with IP 192.168.1.42:

Convert the IP into a 32-bit integer.
Traverse the Trie bit-by-bit from left to right (MSB to LSB).
If at any step we hit a node marked isBlocked = true, the IP belongs to a blacklisted subnet. We stop immediately and block the request.

e x t T im e C o m pl e x i t y : O (W) e x t w h ere W = 32 e x t bi t s (C o n s t an tT im e)

Regardless of whether your database contains 10 subnets or 10,000,000 subnets, checking an IP takes at most 32 bit traversals.

Building the Bitwise Trie in Node.js

Here is a clean implementation of an IP Blacklist Trie:

class TrieNode {
  constructor() {
    this.children = [null, null]; // 0 for bit 0, 1 for bit 1
    this.isBlocked = false;
  }
}

class IPTrie {
  constructor() {
    this.root = new TrieNode();
  }

  // Helper: Convert IPv4 string ("192.168.1.1") to 32-bit Unsigned Integer
  ipToInt(ip) {
    return ip
      .split('.')
      .reduce((acc, octet) => ((acc << 8) + parseInt(octet, 10)) >>> 0, 0);
  }

  // Insert CIDR block (e.g., ipStr = "192.168.1.0", prefixLen = 24)
  addCIDR(ipStr, prefixLen = 32) {
    const ipNum = this.ipToInt(ipStr);
    let node = this.root;

    for (let i = 31; i >= 32 - prefixLen; i--) {
      const bit = (ipNum >>> i) & 1;

      if (!node.children[bit]) {
        node.children[bit] = new TrieNode();
      }
      node = node.children[bit];

      // Short-circuit: if a parent subnet is already blocked, stop
      if (node.isBlocked) return;
    }

    node.isBlocked = true;
  }

  // Search if an IP is blocked (Returns true/false in max 32 steps)
  isIPBlocked(ipStr) {
    const ipNum = this.ipToInt(ipStr);
    let node = this.root;

    for (let i = 31; i >= 0; i--) {
      const bit = (ipNum >>> i) & 1;

      if (!node.children[bit]) {
        return false; // Path doesn't exist -> IP is clean
      }

      node = node.children[bit];

      // Subnet match found!
      if (node.isBlocked) {
        return true;
      }
    }

    return false;
  }
}

// Example Express Middleware Usage
const ipFilter = new IPTrie();

// Blacklist a specific IP and a whole subnet
ipFilter.addCIDR("10.0.0.5", 32);       // Single IP
ipFilter.addCIDR("192.168.1.0", 24);    // 192.168.1.0 - 192.168.1.255

function ipFilterMiddleware(req, res, next) {
  const clientIP = req.ip || req.headers['x-forwarded-for'] || "127.0.0.1";

  if (ipFilter.isIPBlocked(clientIP)) {
    return res.status(403).json({
      error: "Access Denied",
      message: "Your IP or network subnet is blacklisted."
    });
  }

  next();
}

Performance Benchmark & Engineering Takeaways

Sub-Microsecond Traversal: Traversing 32 array pointers in memory executes in nanoseconds, safely outperforming database or external cache lookups.
Minimal Memory Overhead: Shared prefix nodes mean subnets inside the same range reuse existing tree nodes.
Algorithmic Elegance: Converting strings to 32-bit integers allows us to use fast bitwise shift (>>>) and bitwise AND (&) operators directly in the hot code path.

By applying competitive programming tree traversal concepts, we turn a costly linear security check into an ultra-fast constant-time guardrail for production backend services.

Why Fixed-Window Rate Limiters Fail (And How to Fix Them with Math)

Doaa H Alshawwa — Sun, 23 Aug 2026 12:21:02 +0000

If you’ve ever built an Express API, you’ve probably reached for standard rate-limiting middleware to protect your login or payment endpoints from DDoS and brute-force attacks.

Under the hood, most simple limiters use a Fixed-Window Counter. It’s easy to write: count incoming requests, and once the minute rolls over, reset the counter to zero.

However, from a security and algorithmic standpoint, Fixed-Window counters have a massive blind spot.

The Boundary Vulnerability (The 2-Second Spike)

Imagine your endpoint allows a maximum of 100 requests per minute, resetting every full minute on the clock (:00).

Here is how an attacker bypasses that limit without breaking your rules:

At 12:00:59, the attacker fires 100 requests. (Allowed: 100/100 used).
At 12:01:00, the clock resets your counter back to 0.
At 12:01:01, the attacker fires another 100 requests. (Allowed: 100/100 used).

To your server code, everything looks fine. But in reality, 200 requests slammed your backend within a 2-second window. In FinTech or authentication systems, that burst is more than enough to overwhelm payment gateways or run a successful credential-stuffing attack.

The Algorithmic Fix: Sliding Window Counter

To stop boundary spikes, we need a continuously sliding window rather than a rigid clock reset.

Attempt 1: The Sliding Window Log (High Memory)

You store a timestamps array (a Deque) for every user request and drop timestamps older than 60 seconds. While accurate, storing every single request timestamp takes $O(N)$ space. If your API receives millions of requests, your server memory dies instantly.

Attempt 2: Sliding Window Counter (Optimal O(1) Math)

Instead of keeping thousands of timestamps, we track only two integers: the request count of the previous window and the count of the current window.

When a request arrives, we calculate an estimated request count by weighting the previous window based on how much time has passed in the current window:

Estimated Requests = Current Count + (Previous Count \times \frac{Window Size - Time Elapsed}{Window Size})

If the time elapsed in the current window is 75%, we only count 25% of the previous window's traffic.

Time Complexity: O(1) lookup and arithmetic.
Space Complexity: O(1) memory footprint (just two counter variables per IP).

Building the Middleware in Node.js

Here is a lightweight implementation using JavaScript Map to track state:

class SlidingWindowRateLimiter {
  constructor(limit, windowMs) {
    this.limit = limit; // e.g., 100 requests
    this.windowMs = windowMs; // e.g., 60000ms (1 minute)
    this.hits = new Map();
  }

  isAllowed(ip) {
    const now = Date.now();
    const currentWindowKey = Math.floor(now / this.windowMs);
    const timeElapsedInCurrentWindow = now % this.windowMs;

    const record = this.hits.get(ip) || {
      prevWindowKey: currentWindowKey - 1,
      prevCount: 0,
      currWindowKey: currentWindowKey,
      currCount: 0,
    };

    // Roll windows over if time has progressed
    if (record.currWindowKey !== currentWindowKey) {
      if (record.currWindowKey === currentWindowKey - 1) {
        record.prevCount = record.currCount;
      } else {
        record.prevCount = 0; // Previous window is too old
      }
      record.currWindowKey = currentWindowKey;
      record.currCount = 0;
    }

    // Calculate sliding weight formula
    const weight = (this.windowMs - timeElapsedInCurrentWindow) / this.windowMs;
    const estimatedRequests = Math.floor(record.prevCount * weight) + record.currCount;

    if (estimatedRequests >= this.limit) {
      return { allowed: false, currentCount: estimatedRequests };
    }

    // Increment and store current count
    record.currCount += 1;
    this.hits.set(ip, record);

    return { allowed: true, currentCount: estimatedRequests + 1 };
  }
}

// Express Middleware Wrap
const limiter = new SlidingWindowRateLimiter(100, 60000);

function rateLimiterMiddleware(req, res, next) {
  const clientIP = req.ip || req.headers['x-forwarded-for'];
  const result = limiter.isAllowed(clientIP);

  res.setHeader('X-RateLimit-Limit', 100);
  res.setHeader('X-RateLimit-Remaining', Math.max(0, 100 - result.currentCount));

  if (!result.allowed) {
    return res.status(429).json({
      error: 'Too Many Requests',
      message: 'Rate limit exceeded. Please try again shortly.',
    });
  }

  next();
}

Why This Matters for High-Performance Systems

Sub-Millisecond Speed: The decision math executes in fractions of a microsecond without iterating over huge arrays.
Boundary Smoothness: An attacker trying the 12:00:59 / 12:01:01 spike will be blocked instantly because the weight of the 12:00:59 burst carries over into the calculation.
Production Readiness: In a distributed multi-node infrastructure, this exact math scales cleanly to Redis using simple INCR and hash keys.

Applying basic competitive programming data structures and math to API security turns naive middleware into enterprise-grade defense.

How I Stop Webhook Replay Attacks in Node.js & PostgreSQL

Doaa H Alshawwa — Sat, 22 Aug 2026 10:38:18 +0000

Handling payment webhooks sounds straightforward—until network retries hit your server three times in a row, or an attacker intercepts a valid payload and tries to credit their balance twice.

Validating signatures is step one, but it won't protect you from a replay attack where a valid, signed payload gets resent. Here is how to set up a clean, multi-layer defense in Node.js with PostgreSQL to ensure every webhook payload runs exactly once.

Why Postgres for Idempotency?

You could store processed event IDs in Redis, but if your cache flushes or a container restarts during a high-traffic spike, you lose state.

Using PostgreSQL with a unique constraint guarantees database-level isolation. If two identical requests hit your backend at the exact same millisecond, Postgres handles the lock and drops the duplicate.

-- Track processed webhook events
CREATE TABLE processed_webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL,
    signature VARCHAR(255) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);

-- Fast lookups on incoming events
CREATE INDEX idx_processed_webhooks_event_id ON processed_webhooks(event_id);

The Express Middleware

Our security check handles three things before touch point execution:

Timestamp Freshness: Kills requests older than 5 minutes to prevent stale replay attempts.
HMAC Check: Uses crypto.timingSafeEqual to avoid timing side-channel attacks.
Database Check: Queries Postgres for duplicate event_id records.

const crypto = require('crypto');
const { Pool } = require('pg');

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET || 'super_secret_key';

// Reject requests older than 5 minutes
const MAX_AGE_SECONDS = 300; 

async function verifyPaymentWebhook(req, res, next) {
    const signature = req.headers['x-signature'];
    const timestamp = req.headers['x-timestamp'];
    const { event_id } = req.body;

    if (!signature || !timestamp || !event_id) {
        return res.status(400).json({ error: 'Missing security headers or payload event_id' });
    }

    // 1. Clock skew / freshness check
    const now = Math.floor(Date.now() / 1000);
    const reqTime = parseInt(timestamp, 10);

    if (isNaN(reqTime) || Math.abs(now - reqTime) > MAX_AGE_SECONDS) {
        return res.status(401).json({ error: 'Stale request / timestamp out of bounds' });
    }

    // 2. Validate HMAC Signature
    const payload = `${timestamp}.${JSON.stringify(req.body)}`;
    const expectedSignature = crypto
        .createHmac('sha256', WEBHOOK_SECRET)
        .update(payload)
        .digest('hex');

    const sigBuf = Buffer.from(signature);
    const expectedBuf = Buffer.from(expectedSignature);

    // Constant-time comparison prevents timing attacks
    if (sigBuf.length !== expectedBuf.length || !crypto.timingSafeEqual(sigBuf, expectedBuf)) {
        return res.status(403).json({ error: 'Invalid signature' });
    }

    // 3. PostgreSQL Idempotency Check
    try {
        const { rows } = await pool.query(
            'SELECT id FROM processed_webhooks WHERE event_id = $1',
            [event_id]
        );

        if (rows.length > 0) {
            return res.status(409).json({ error: 'Event already processed' });
        }

        next();
    } catch (err) {
        console.error('Webhook verification error:', err);
        return res.status(500).json({ error: 'Database check failed' });
    }
}

module.exports = { verifyPaymentWebhook };

Wiring the Route

Now attach the middleware to your payment route and log the event inside Postgres as part of the transaction block.

const express = require('express');
const { verifyPaymentWebhook } = require('./middleware/webhookSecurity');

const app = express();
app.use(express.json());

app.post('/api/v1/webhooks/payment', verifyPaymentWebhook, async (req, res) => {
    const { event_id, amount, userId } = req.body;
    const signature = req.headers['x-signature'];

    try {
        // Mark event as processed first
        await pool.query(
            'INSERT INTO processed_webhooks (event_id, signature) VALUES ($1, $2)',
            [event_id, signature]
        );

        // Core business logic (e.g., updating balance)
        console.log(`Crediting $${amount} to user${userId}`);

        return res.status(200).json({ status: 'ok' });
    } catch (err) {
        console.error('Error handling webhook payload:', err);
        return res.status(500).json({ error: 'Processing error' });
    }
});

How to Test This Setup

When testing locally with Postman or curl:

Send a valid request. You should get a 200 OK.
Immediately hit send again with the exact same payload. The server should return 409 Conflict because Postgres caught the duplicate event_id.
Change the x-timestamp header to a time 10 minutes ago. The server should return 401 Unauthorized.

Structuring webhook security this way protects your system even if payment providers trigger aggressive retry loops or malicious actors try resending old traffic.