Exactly-Once Delivery: Myth vs Reality

"Does your system support exactly-once delivery?"

If you've worked with webhooks, message queues, or any distributed system, you've probably asked this question. And if someone answered "yes" without hesitation, they either misunderstood the question or are selling you something.

Here's the uncomfortable truth: exactly-once delivery is impossible in distributed systems. Not "really hard." Not "we haven't figured it out yet." Mathematically, provably impossible.

But don't despair. Understanding why it's impossible leads to building systems that are actually reliable. Let's dig in.

The Two Generals Problem

The impossibility of exactly-once delivery comes from a fundamental result in distributed systems theory called the Two Generals Problem.

Imagine two armies on opposite sides of a valley, needing to coordinate an attack. They can only communicate by sending messengers through the valley—but messengers might be captured. How can both generals be certain they'll attack at the same time?

• General A sends: "Attack at dawn"
• General B receives it, sends back: "Confirmed, attacking at dawn"
• But did General A receive the confirmation?
• General B sends another confirmation...
• But did General B's second confirmation arrive?

This regress is infinite. There's no number of messages that can guarantee both parties know the other received their message. This was proven impossible in 1975, and it applies directly to networks.

"In a network, you can never be certain that your message was received, and the recipient can never be certain you know they received it."

What This Means for Webhooks

When Stripe sends you a webhook, here's what can happen:

This isn't a bug in Stripe's system. It's not a bug in your system. It's a fundamental property of networks. The sender cannot distinguish between "message lost" and "acknowledgment lost."

The Three Delivery Guarantees

Every messaging system offers one of three guarantees:

*When people say "exactly-once," they usually mean at-least-once delivery + idempotent processing. The delivery still happens multiple times, but the effect only happens once.

This distinction matters. You can't prevent duplicates from arriving. But you can prevent duplicates from causing problems.

The Real Solution: Idempotency

An operation is idempotent if performing it multiple times has the same effect as performing it once. This is the key to handling webhook duplicates safely.

Here's a simple idempotent webhook handler:

// ❌ NOT idempotent - will charge twice on duplicate
app.post('/webhook', async (req, res) => {
  const { customerId, amount } = req.body;
  await chargeCustomer(customerId, amount);
  res.sendStatus(200);
});

// ✅ Idempotent - safe to receive duplicates
app.post('/webhook', async (req, res) => {
  const { eventId, customerId, amount } = req.body;

  // Check if we've already processed this event
  const existing = await db.get(
    'SELECT * FROM processed_events WHERE event_id = ?',
    eventId
  );

  if (existing) {
    // Already processed, just acknowledge
    return res.sendStatus(200);
  }

  // Process the event
  await chargeCustomer(customerId, amount);

  // Record that we processed it
  await db.run(
    'INSERT INTO processed_events (event_id, processed_at) VALUES (?, ?)',
    eventId, Date.now()
  );

  res.sendStatus(200);
});

Idempotency Keys: Your Best Friend

Most webhook providers include a unique identifier with each event:

• Stripe: id field (e.g., evt_1234567890)
• GitHub: X-GitHub-Delivery header
• Shopify: X-Shopify-Webhook-Id header
• Twilio: MessageSid or CallSid

Use this ID as your idempotency key. Store it when you successfully process an event, and check for it before processing any new event.

-- Create table with unique constraint
CREATE TABLE processed_events (
  event_id TEXT PRIMARY KEY,  -- Prevents duplicates at DB level
  processed_at INTEGER NOT NULL,
  payload TEXT
);

-- Insert with conflict handling
INSERT INTO processed_events (event_id, processed_at, payload)
VALUES (?, ?, ?)
ON CONFLICT (event_id) DO NOTHING;  -- Silently ignore duplicates

Making Operations Naturally Idempotent

Sometimes you can redesign your operations to be inherently idempotent:

Cleaning Up Old Idempotency Keys

You don't need to store idempotency keys forever. Most webhook providers retry within a window of hours or days. A retention period of 7-30 days is typically sufficient.

// Daily cleanup job
async function cleanupOldIdempotencyKeys() {
  const thirtyDaysAgo = Date.now() - (30 * 24 * 60 * 60 * 1000);

  await db.run(
    'DELETE FROM processed_events WHERE processed_at < ?',
    thirtyDaysAgo
  );
}

How EventDock Handles This

At EventDock, we provide idempotency as a built-in feature:

• Automatic deduplication: We hash each incoming webhook (provider + event ID + payload) and reject duplicates before they reach your server
• Configurable window: Set your deduplication window from hours to days
• At-least-once to your endpoint: We guarantee delivery with retries, but dedupe at ingestion so you only see each event once
• Full visibility: See when duplicates were detected and filtered in your dashboard

This means you can write simple webhook handlers without complex idempotency logic—we handle it at the infrastructure layer.

Summary

The next time someone asks if you support "exactly-once delivery," you'll know the right answer: "We do at-least-once with idempotent processing, which is the only way to achieve reliable delivery in the real world."