Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Make job starts safe for retries, webhooks, signups, and payments.

​
Prerequisites

  • A stable identifier for the logical work, such as a user ID, order ID, payment ID, or webhook event ID

​
Workflow

1
Choose a key that represents the logical work.
2
Pass that key when starting or enqueueing the job.
3
Reuse the same key when the same request is retried.
4
Treat a key with a different payload as an error to fix, not a new job.

​
The problem

APIs retry. Browsers double-submit. Payment providers resend webhooks. Workers restart after partial progress. Without idempotency, those duplicates can send two emails, charge twice, provision twice, or process the same webhook more than once.

​
The solution

An idempotency key tells StackShift that repeated starts represent the same logical job. 
await stackshift.queue('emails').enqueue(
  'sendVerificationEmail',
  { userId: '123' },
  { idempotencyKey: `verify:123` }
)

​
Behavior

  • Same key and same payload: StackShift reuses the existing run.
  • Same key and different payload: StackShift returns an error because the caller is trying to reuse a key for different work.
  • Retries are safe because the same logical operation maps to the same run.
  • Webhooks are safe because repeated delivery can reuse the provider event ID as the key.

​
Real use cases

  • Payments: use the payment intent, transaction, or provider event ID.
  • Webhooks: use the webhook event ID.
  • User signup: use the user ID or email-verification token ID.

​
Expected result

Duplicate requests reuse the same run instead of doing the same side effect twice.

Event Waiting + Correlation

Pause a workflow until the right external event arrives, then resume the correct run.

Retries & Failure Handling

Durable Jobs retries transient failures, preserves completed steps, and gives failed work a clear recovery path.