Laatst bijgewerkt: 2026-03-03•3 min leestijd

Idempotentie

Idempotentie voorkomt dubbele verzendingen wanneer je systeem een verzoek opnieuw probeert.

Hoe het werkt

Voeg bij elk verzendverzoek een Idempotency-Key-header toe. De key is een unieke string die je genereert — doorgaans een UUID gekoppeld aan de bedrijfsgebeurtenis.

curl -X POST https://truncus.co/api/v1/emails/send \
  -H "Authorization: Bearer $TRUNCUS_API_KEY" \
  -H "Idempotency-Key: bestelling_12345_factuur" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "facturatie@jouwdomein.nl",
    "subject": "Factuur #1234",
    "html": "<p>Je factuur is klaar.</p>"
  }'

Gedrag

Als een verzoek met dezelfde idempotency key al is verwerkt:

  • De originele message_id en status worden teruggegeven
  • Er wordt geen nieuwe e-mail verstuurd
  • De response is identiek aan de originele

Idempotency keys verlopen na 24 uur. Na vervallen triggert dezelfde key een nieuwe verzending.

Wanneer idempotentie gebruiken

  • Betalingsbevestigingen — één e-mail per betaling, ongeacht retries
  • Webhook-handlers — veilig herhaalbaar bij bezorgingsfout
  • Agent-workflows — heruitvoeringen leveren hetzelfde resultaat
  • Elke verzending waarbij duplicaten de ontvanger zouden beïnvloeden

SDK-gebruik

const response = await truncus.emails.send({
  to: 'user@example.com',
  from: 'facturatie@jouwdomein.nl',
  subject: 'Factuur #1234',
  html: factuurHtml,
}, {
  idempotencyKey: `bestelling_${bestellingId}_factuur`
})

Key-ontwerp

Een goede idempotency key codeert de bedrijfsgebeurtenis, niet het verzoek:

// Goed: gekoppeld aan de gebeurtenis
const key = `betaling_${betalingId}_bon`

// Goed: stabiel bij retries
const key = `gebruiker_${gebruikerId}_welkom`

// Slecht: verandert bij retry
const key = crypto.randomUUID()

Als er geen idempotency key wordt opgegeven, wordt elk verzoek als een nieuwe verzending behandeld.

Idempotentie