queue-debouncing

Laravel Queue Debouncing

Core Principle

• Debounce only work where the latest state safely replaces previous triggers.
• Debounce belongs to a replaceable outcome, not to a generic entity.
• A debounce key must describe what result may be safely replaced, not only which model changed.

Good debounce keys describe the replaceable outcome:

read-model:order:123
crm-sync:user:42
search-index:post:99
usage-summary:account:7
preview-render:document:15

Bad debounce keys are too generic and collapse unrelated business events:

order:123
user:42
account:7
project:15

Allowed Use Cases

Debouncing is allowed only for convergent work where intermediate states may be skipped safely:

• Search index rebuilds
• Cache refreshes
• Read model rebuilds
• CRM/profile snapshot syncs
• Preview/render regeneration
• Aggregate/statistical summary recalculation
• Expensive derived data refreshes

Forbidden Use Cases

Never debounce meaningful business events where each occurrence has its own meaning. Do not debounce:

• Payments
• Refunds
• Password changes
• Security alerts
• Audit logs
• Webhook event recording
• Fulfillment or shipment transitions
• User-visible notifications expected immediately
• Anything where order, timing, or exact occurrence matters

Split Mixed-Urgency Workflows

Split urgent and replaceable work into separate jobs. Urgent jobs must stay immediate and idempotent; convergent jobs may be debounced.

Bad — one generic sync job hides both urgent and convergent side effects:

SyncOrder::dispatch($order->id);

Good — explicit jobs with clear business meaning:

ProcessCapturedPayment::dispatch($payment->id, $order->id);

RefreshOrderReadModel::dispatch($order->id);
SyncOrderSnapshotToCrm::dispatch($order->id);

Idempotency Is Still Required

Debounce does not replace idempotency.

• Debounce answers: should we avoid running this repeated work too many times?
• Idempotency answers: is the result still correct if this job runs more than once?