Idempotency-Key lo impedisce: la stessa chiave ripete la prima risposta invece di rifare l’operazione.
Dove si usa
Su questi endpoint è obbligatoria, perché l’operazione costa o non si annulla:
Senza l’header, questi endpoint rispondono
400 invalid_request.
È facoltativa sulle altre creazioni e azioni: POST /patients, POST /appointments/{id}/move, /cancel, /confirm e /status, POST /treatment-plans, POST /tasks, POST /leads, POST /leads/{id}/activities e /convert, POST /calls, POST /voice/handoff, POST /webhook-deliveries/{id}/redeliver. Gli endpoint che non la prevedono la ignorano.
Comportamento
La prima risposta si conserva per 24 ore. Dopo, la stessa chiave vale come nuova.
La chiave è legata alla chiave API, all’operazione e al corpo. Cliniche diverse possono usare la stessa stringa senza disturbarsi.
Risposte con un segreto
POST /webhook-endpoints e POST /webhook-endpoints/{id}/rotate-secret mostrano un segreto una volta sola, e quella risposta non viene conservata. Una seconda richiesta con la stessa chiave risponde 409 conflict con details.reason: "response_not_stored", senza generare un altro segreto.
Scegliere la chiave
Una chiave per ogni operazione, non per ogni tentativo. Per un agente vocale: l’id della telefonata più l’azione, per esempio<id-telefonata>-prenota. Ogni ripetizione della stessa prenotazione usa la stessa chiave; una seconda prenotazione nella stessa telefonata ne usa un’altra.