Design an Event and Webhook Platform

Write each event in the same database transaction as the state change, an outbox, so events exist exactly when changes commit. A relay publishes them to a log; a dispatcher matches subscriptions and delivers to each endpoint from its own queue, signed and retried with backoff. Keep events 30 days so merchants can replay what they missed.

hardPattern: Message queues and async work·From Devana's Stripe question set

Problem

Design the system that turns internal state changes, such as a payment succeeding or a refund being issued, into events that merchants subscribe to and receive at their own HTTPS endpoints.

Cover event generation, subscription filtering, delivery, how a merchant can tell an event really came from you, and how a merchant recovers after their endpoint was down.

POST /webhook_endpoints              {url, event_types[]}  -> {id, signing_secret}
GET  /events?type=&created_after=    -> a page of events
POST /webhook_endpoints/{id}/replay  {from, to}  -> {replay_id}
Delivery: POST to the merchant's URL with a signature header "t=<unix time>,v1=<hex HMAC>"

This is one of Devana's own questions, written in the style of Stripe's interviews. It is not a question leaked from Stripe, and Devana is not affiliated with Stripe.

Requirements

• 10^6 events per minute.
• Merchants subscribe to specific event types.
• Delivery is at least once, so merchants must tolerate duplicates.
• Events are retained and replayable for 30 days.
• A slow or failing merchant endpoint must not delay anyone else's events.

Scenarios

Hints

Open one at a time, and try the problem again after each.

A worked answer

How to say it in the interview

Start with the dual write problem, because the question asks for events "if and only if the state change committed": name the crash windows on both sides, then the outbox. Then isolation per endpoint, and only then retries and signatures. Say plainly that delivery is at least once and what the merchant does about duplicates.

The core in code

The part merchants build against, so it has to be exactly right: signing a delivery and verifying it. The signature covers the timestamp and the raw body, and verification rejects stale timestamps so a captured request cannot be replayed later.

Python

import hashlib
import hmac

def sign(secret, timestamp, payload):
    message = f"{timestamp}.{payload}".encode()
    return hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()

def signature_header(secret, timestamp, payload):
    return f"t={timestamp},v1={sign(secret, timestamp, payload)}"

def verify(secret, header, payload, now, tolerance=300):
    try:
        parts = dict(item.split("=", 1) for item in header.split(","))
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(now - timestamp) > tolerance:            # stale: possibly a replay
        return False
    expected = sign(secret, timestamp, payload)
    return hmac.compare_digest(expected, parts.get("v1", ""))   # constant time

JavaScript (Node.js)

const crypto = require("node:crypto");

function sign(secret, timestamp, payload) {
  return crypto.createHmac("sha256", secret).update(timestamp + "." + payload).digest("hex");
}

function signatureHeader(secret, timestamp, payload) {
  return "t=" + timestamp + ",v1=" + sign(secret, timestamp, payload);
}

function verify(secret, header, payload, now, tolerance = 300) {
  const parts = {};
  for (const item of header.split(",")) {
    const i = item.indexOf("=");
    if (i > 0) parts[item.slice(0, i)] = item.slice(i + 1);
  }
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !parts.v1) return false;
  if (Math.abs(now - timestamp) > tolerance) return false; // stale: possibly a replay
  const expected = Buffer.from(sign(secret, timestamp, payload));
  const given = Buffer.from(parts.v1);
  return expected.length === given.length && crypto.timingSafeEqual(expected, given); // constant time
}

Both versions are tested against the same cases, including every example on this page.

• The signature is over the raw body exactly as sent. A merchant who parses the JSON and serializes it again before verifying gets a different string and a failed check.
• Comparing with == can leak, through timing, how many characters matched; compare_digest and timingSafeEqual take the same time either way.
• A five-minute tolerance limits replays without rejecting deliveries delayed by ordinary clock skew.

Follow-up questions

Common mistakes

• Publishing to the queue after the commit, with no plan for a crash in between.
• One shared delivery queue, so a single slow merchant delays everyone.
• Retrying immediately and indefinitely, which turns a merchant's outage into a flood when they recover.
• Signing a parsed and re-serialized body instead of the exact bytes sent.

Practice it in a mock interview

Reading a solution and explaining one under questioning are different skills. The button below starts this problem as a voice mock interview with Josh, Devana's AI interviewer, with a whiteboard he can read.

Practice this problem in a mock interview

Related problems

• Design a URL Shortener at Scale: Key generation, a cache-first redirect path, and analytics kept off the hot path.
• Deduplicate a Stream of Retried Events: A hash set for membership and a queue in arrival order, so expired IDs fall out of the window.
• Message queues and async work: the pattern guide, with more practice questions.