monnify BUILD

SESSIONS

SESSION 02

Webhooks and Idempotency in Production

SPEAKER

Auwal MS

Lead, Developer Relations & Integration Support

Webhooks, Mechanically

• If your handler doesn’t acknowledge receipt, Monnify assumes delivery failed - and tries again.
• Every 5 minutes, up to 12 times. That’s up to 12 chances for the same event to land on your server.

The Lie of “Exactly-Once” Delivery

Why Webhooks Retry

Network flaps, worker timeouts, 502 proxies, or database locks trigger automatic gateway retries.

The Consumer Invariant

Idempotency is 100% the receiver’s responsibility. The gateway guarantees delivery, not deduplication. ✓ Golden Rule: Receiving the exact same payload 10 times must produce identical business state.

The Race Condition in Naive Code

The Flawed Check-Then-Act Flow

// DEADLY: App-layer check is NOT atomic
const tx = await db.find({ ref });
if (!tx) {
    // Millisecond gap: concurrent retry passes
    await wallet.credit(amount); // 2x CREDIT!
    await db.save({ ref, status: 'PAID' });
}

Parallel Request Collisions Two containers evaluate condition simultaneously before either writes.