Durable Jobs
Idempotency
LiveUse idempotency keys so duplicate requests do not create duplicate work.
Goal
Make job starts safe for retries, webhooks, signups, and payments.
Current status
Live
This area is documented as current, user-reliable behavior.
Workflow
- 1Choose a key that represents the logical work.
- 2Pass that key when starting or enqueueing the job.
- 3Reuse the same key when the same request is retried.
- 4Treat 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.
Send verification email once
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.