Idempotency Guide

Why Idempotency Matters

Syllecta prevents duplicate writes by enforcing one record per (tenant, scope, key) pair. The same principle applies to webhooks: replays are filtered before they reach your backend.

Core Concepts

• Scope – logical grouping of requests (e.g., orders, payouts).
• Key – unique identifier within the scope (order-1001, invoice-55).
• Lock – POST /v1/record returns locked: true when you may proceed with work.
• TTL – records live for 24 hours by default (configurable).

Recommended Flow

1. Call POST /v1/record with scope + key.
2. If cached: true, reuse the stored record and skip the write.
3. If locked: true, perform the write and PUT /v1/record with the final body/status.
4. If locked: false, wait retryAfterMs and try again.

Example Workflow

curl -X POST https://cloud.syllecta.example/v1/record \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "orders",
    "key": "order-2001"
  }'

curl -X PUT https://cloud.syllecta.example/v1/record \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "orders",
    "key": "order-2001",
    "body": {
      "status": "paid"
    }
  }'

Handling Responses

• Record already exists:

{
  "cached": true
}

Reuse stored record.

• Lock acquired:

{
  "locked": true
}

Execute write and save.

• Another request is in progress:

{
  "locked": false,
  "retryAfterMs": 1500
}

Retry after the suggested delay.

• Usage limit exceeded:

{
  "status": 429
}

Review plan usage.

Webhook Idempotency

• Syllecta dedupes webhook events using provider IDs (Stripe event.id, Shopify X-Request-Id, etc.).
• Duplicates return:

{
  "ok": true,
  "cached": true
}

and your callback is not hit again.

• You can see replay counts per provider in Events by filtering on status cached.

Checklist

• Each logical write uses a stable scope + key.
• Handlers only proceed after locked: true.
• Retries respect retryAfterMs.
• Usage is monitored in Backoffice.