Idempotence

Une coupure réseau ne dit pas si votre écriture a abouti. Rejouez-la sans risque en passant un en-tête Idempotency-Key, de 255 caractères au plus, généré par vos soins :

curl


curl https://api.ophelix.fr/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: 7f9c2ba4-e88f-4a1c-9d11-3c5e8a1b2d40" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://exemple.fr/hook", "enabled_events": ["claim.*"]}'

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.ophelix.fr']);
 
$response = $client->post('/v1/webhook-endpoints', [
    'headers' => [
        'Authorization' => 'Bearer sk_test_…',
        'Idempotency-Key' => '7f9c2ba4-e88f-4a1c-9d11-3c5e8a1b2d40',
    ],
    'json' => ['url' => 'https://exemple.fr/hook', 'enabled_events' => ['claim.*']],
]);

TypeScript


const response = await fetch('https://api.ophelix.fr/v1/webhook-endpoints', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_…',
    'Content-Type': 'application/json',
    'Idempotency-Key': '7f9c2ba4-e88f-4a1c-9d11-3c5e8a1b2d40',
  },
  body: JSON.stringify({ url: 'https://exemple.fr/hook', enabled_events: ['claim.*'] }),
})

La même clé et le même corps rendent la réponse d’origine pendant 24 heures, avec l’en-tête Idempotent-Replayed: true.
La même clé avec un autre corps est refusée : idempotency_key_reused.
Tant que la première requête tourne, une requête identique reçoit idempotency_key_in_progress : réessayez un instant plus tard.
Une erreur 5xx libère la clé : rejouez-la telle quelle.

Une clé vaut pour une organisation et un mode.

POST /v1/workstation-pairing-codes ignore cet en-tête : rejouer la réponse demanderait de garder le code en clair. Deux appels donnent deux codes, et le second expire seul.