Idempotency

Stormedo has two separate idempotency boundaries:

1. Publisher idempotency prevents the same submission from creating multiple request resources.
2. Receiver idempotency prevents duplicate delivery attempts from repeating a business side effect.

You usually need both.

Publisher idempotency

Send an Idempotency-Key header when creating a request:

Idempotency-Key: order-123-created

The reservation is scoped to the project and retained for 24 hours.

During that window:

• The same key with the same input returns the original request.
• The same key with different input returns 409 Conflict.
• A request without a key always creates new work.

Use a stable business identifier when your application already knows what one logical operation means.

curl --request POST \
  'https://api.stormedo.com/send?url=https://your-app.example/webhook' \
  --header "Authorization: Bearer $STORMEDO_TOKEN" \
  --header 'Idempotency-Key: order-123-created' \
  --header 'Content-Type: application/json' \
  --data '{"order_id":"ord_123"}'

SDK submission behavior

The JavaScript and Python SDKs generate one key per logical send. If the API call is interrupted before receiving a response, the SDK safely retries once with the same key.

Pass idempotencyKey in JavaScript or idempotency_key in Python when you want the key to represent a business operation across separate application calls.

Receiver idempotency

Stormedo provides at-least-once delivery. A destination can process an attempt successfully before Stormedo records the response, so the same request can arrive again.

Every attempt includes:

Stormedo-Request-Id: req_33uZSQsVaf8aZjDuzkuAq

After authenticating the delivery, store this stable request ID before, or atomically with, the business side effect.

A common database pattern is:

BEGIN
  insert request_id into processed_deliveries with a unique constraint
  if the insert succeeded, apply the business side effect
COMMIT

When the unique insert reports that the ID already exists, return a successful response without applying the side effect again.

Do not use attempt identity

Attempts are operational records. They can change between deliveries of the same logical request.

Deduplicate with the stable Stormedo-Request-Id, not a timestamp, response status, or attempt number.

Batch and schedule keys

Batch creation requires a key for the complete batch and can also include an idempotency key for each item.

Schedule creation requires an Idempotency-Key. Repeating the same definition with the same key returns the original schedule, while changing the definition returns 409 Conflict.