Skip to main content
When an external system triggers a workflow via the fsckmsft API, it may send the same event more than once — a webhook that retries on timeout, a queue processor that replays on failure, or a deployment script that runs twice by accident. Without a safeguard, each delivery creates a new workflow run, potentially sending duplicate notifications, creating duplicate records, or charging a customer twice. Idempotency keys are that safeguard: pass the same key with the same request, and fsckmsft guarantees the workflow runs exactly once.

​
How idempotency works

When you include an Idempotency-Key header in a workflow trigger request, fsckmsft records the key alongside the resulting run ID. If another request arrives with the same key within the 24-hour retention window, fsckmsft returns the original run’s response immediately — without starting a new run. The second (and any subsequent) request is treated as a duplicate, not an error: you receive an HTTP 200 response with the original run details and an X-Idempotent-Replayed: true header.

​
Trigger a workflow with an idempotency key

Send a POST request to the workflow trigger endpoint and include the Idempotency-Key header. Use any unique string as the key — a UUID, a content hash of the event payload, or the event ID from your source system all work well. 
curl -X POST https://api.fsckmsft.org/v1/workflows/{id}/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-event-id-123" \
  -d '{"data": {"task_id": "t_abc123"}}'
A successful first-time trigger returns: 
{
  "run_id": "run_9kXmP2vQwL",
  "status": "started",
  "workflow_id": "wf_7hJdN1",
  "idempotent_replayed": false
}
A duplicate request with the same Idempotency-Key returns: 
{
  "run_id": "run_9kXmP2vQwL",
  "status": "completed",
  "workflow_id": "wf_7hJdN1",
  "idempotent_replayed": true
}
The Idempotency-Key value is case-sensitive and scoped to your workspace — keys from different workspaces never collide. Keys are limited to 255 characters. If you omit the header entirely, fsckmsft always starts a new run.

​
Key retention window

Idempotency keys are retained for 24 hours from the time the first request is received. After the retention window expires, the key is removed from fsckmsft’s records. A new request with that same key will be treated as a fresh trigger and start a new run. Design your key generation strategy with this window in mind:
  • For event-driven integrations, use the upstream event’s own unique ID (e.g., evt_stripe_ch_xxx, gh_push_sha_abc). Event IDs from source systems are already unique and stable.
  • For scheduled or batch processes that may run again within 24 hours, incorporate a timestamp or sequence number into the key so that legitimate re-runs use a different key.

​
Example use case: webhook retry safety

A payment provider sends a payment.succeeded webhook to your fsckmsft workflow trigger endpoint. If your server returns a 5xx response (perhaps briefly during a deployment), the payment provider retries the webhook up to three times over the next hour. Without idempotency, each retry starts a new workflow run — potentially issuing three duplicate receipts and three duplicate license activations. With idempotency:
  1. Your webhook handler reads the event ID from the provider’s payload: "id": "evt_1OtV4z2eZvKYlo2C3BXGKQ8".
  2. It forwards the event to fsckmsft with Idempotency-Key: evt_1OtV4z2eZvKYlo2C3BXGKQ8.
  3. The first delivery starts the run; the two retries receive idempotent_replayed: true and no additional runs are created.
# First delivery — starts the run
curl -X POST https://api.fsckmsft.org/v1/workflows/{id}/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_1OtV4z2eZvKYlo2C3BXGKQ8" \
  -d '{"data": {"payment_id": "pay_abc", "amount": 4900, "currency": "usd"}}'

# Retry by payment provider — safely deduplicated, no new run
curl -X POST https://api.fsckmsft.org/v1/workflows/{id}/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_1OtV4z2eZvKYlo2C3BXGKQ8" \
  -d '{"data": {"payment_id": "pay_abc", "amount": 4900, "currency": "usd"}}'

​
FAQ

No. Idempotency keys apply only to API-triggered workflows (via the /trigger endpoint). Event-based and scheduled triggers managed entirely within fsckmsft use internal deduplication mechanisms that you do not need to configure manually.
fsckmsft ignores the new payload and returns the response from the original run. The key lookup takes precedence over the request body. If you need to trigger the workflow with different data, use a new, unique idempotency key.
Yes. Open the workflow’s run history in Automation → Workflows → [workflow name] → Runs. Deduplicated requests appear as Replayed entries alongside their original run, making it easy to audit deduplication activity.