Guide: Implementing idempotency keys for all Claw-originated actions.

If you're using Claw's API for anything beyond toy scripts, you'll eventually hit duplicate operations. Their webhooks can replay, your scripts can retry, and suddenly you've got two "Customer X" records in your ERP. The fix is idempotency keys on every POST, PUT, or PATCH.

Claw supports the standard `Idempotency-Key` header. The pattern is simple: generate a unique key for each distinct *intent*, store it, and reuse it on retries.

**Implementation Rules**
* Generate the key on your side (UUID v4 works).
* The key must be unique for each unique *action* on a *resource*. Changing a single field in the payload? That's a new key.
* Claw's idempotency window is at least 24 hours. Keep your keys for longer.

**Where to get/store the key**
Don't overthink it. For a middleware flow (Workato/Celigo/etc.):
1. **At trigger:** Create the key at the start of the job. Use the job's execution ID if available, or generate a UUID.
2. **Before the API call:** Check a persistent datastore (like a recipe datatable) for a previously stored successful result using your generated key.
3. **If found:** Return the stored result. Skip the call.
4. **If not found:** Proceed, sending the `Idempotency-Key: your-key-here` header.
5. **On success:** Store the key and the relevant API response (at minimum the new record's ID) in your datastore.

**Example in a Workato recipe formula**
This generates a deterministic key for a "create order" action, factoring in the source order ID and the operation.

```ruby
"claw-create-order-" + $source_order_number + "-" + $execution_id
```

**What this solves**
* Duplicate records from webhook retries.
* Duplicate records from your own recipe/script retries due to transient errors.
* Provides a clean audit trail for debugging.

Without this, you're just hoping the network and all systems are perfectly reliable. They aren't.