Idempotency

Every POST, PATCH, PUT, and DELETE request against /v1/* requires an Idempotency-Key header. The key makes retries safe: replaying with the same key returns the cached response, while replaying the same key with a different body is rejected.

Header contractCopy Anchor Link

POST /v1/webhook-endpoints HTTP/1.1
Authorization: Bearer sbt_live_...
Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12
Content-Type: application/json

• Opaque string, required on every mutation.
• Any format works — generate a UUID v4 per call.
• Omit the header and Subscriby returns IDEMPOTENCY_KEY_MISSING (HTTP 400).

Replay semanticsCopy Anchor Link

Successful 2xx JSON responses are cached under sha256(token_id:method:path:key) for 24 hours, with the response body encrypted at rest — the one-time secrets in a token mint or a webhook endpoint registration never sit in the cache in clear text. After that, the same key rotates out of cache and behaves as a fresh request. 4xx and 5xx responses are not cached — callers are free to retry them.

Request body fingerprintCopy Anchor Link

Reuse detection hashes the full raw request body (SHA-256). Two requests are "the same" when their token, method, path, key, and body all match byte-for-byte. That's stricter than Stripe's fingerprinting model and keeps accidental reuse obvious.

Client-side recipeCopy Anchor Link

A safe retry loop:

$key = (string) Str::uuid();

$response = Http::withHeaders([
    'Authorization' => "Bearer {$token}",
    'Idempotency-Key' => $key,
    'Content-Type' => 'application/json',
])->retry(
    times: 3,
    sleepMilliseconds: 500,
    when: fn ($exception, $request) => $exception?->response?->status() >= 500,
)->post('https://api.subscriby.net/v1/webhook-endpoints', [
    'name' => 'Zapier hook',
    'url' => 'https://hooks.zapier.com/...',
    'events' => ['subscription.created'],
]);

If the first attempt succeeds and the second attempt's retry fires anyway (e.g. your client timed out on a 200 it never saw), the second call hits the cache and returns the same response — you never double-register the endpoint.

What doesn't require a keyCopy Anchor Link

• GET requests — naturally idempotent.
• Public routes such as /.well-known/ai-plugin.json, /abilities.json, /openapi.json, and /v1/ping.
• Webhook deliveries from Subscriby → your endpoint (those carry their own event ID for consumer-side de-duplication).

RelatedCopy Anchor Link

• Rate limiting
• Error envelope