Handling Retried Webhooks Idempotently in PHP

Deduplicate webhook event IDs before performing repeated side effects. The examples separate the essential operation from the conditions a production implementation must enforce.

What It Does

Deduplicate webhook event IDs before performing repeated side effects.

Prerequisites

Use a dedicated development environment with test accounts and records. Separate authorization, validation and error handling from response formatting; never copy demonstration-only secrets into production.

Example 1: Core Behavior

This scenario applies the exact rule described in the guide, with controlled sample values.

<?php
$eventId="evt_1"; $seen=["evt_1"=>true]; echo isset($seen[$eventId])?"Acknowledge without side effect":"Process";

Example 2: Alternative or Failure Case

This scenario applies the exact rule described in the guide, with controlled sample values.

<?php
$eventId="evt_2"; $seen=["evt_1"=>true]; if(!isset($seen[$eventId])) echo "Insert unique event ID and business change in one transaction";

Practical Example: Applying the Rule

This practical workflow performs the relevant operation, with strict error checks. Configure the required transport or database driver before running it.

<?php
$pdo = new PDO('sqlite::memory:', null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$pdo->exec('CREATE TABLE processed_events (id TEXT PRIMARY KEY, processed_at TEXT NOT NULL)');
$eventId = 'evt_104';
$pdo->beginTransaction();
try {
    $stmt = $pdo->prepare('INSERT OR IGNORE INTO processed_events (id, processed_at) VALUES (?, CURRENT_TIMESTAMP)');
    $stmt->execute([$eventId]);
    if ($stmt->rowCount() === 1) {
        // Apply the associated business change in this same database transaction.
        echo 'Process exactly once at this database boundary';
    } else { echo 'Already processed; acknowledge duplicate'; }
    $pdo->commit();
} catch (Throwable $e) { if ($pdo->inTransaction()) $pdo->rollBack(); throw $e; }

Important Behavior and Edge Cases

Use a unique database constraint and a transaction rather than an in-memory array.

Comparison with Related Functions or Patterns

Common Beginner Mistakes

Key Takeaways

• Deduplicate webhook event IDs before performing repeated side effects.
• Use a unique database constraint and a transaction rather than an in-memory array.
• A valid signature authenticates the sender but does not prove an event is new.

Select this API or pattern based on its documented behavior and the trust boundaries in your own application, and test all external integrations against their actual deployments.