Idempotency

A network can fail after the platform did its work and before you got the answer. Without a safeguard, retrying would do the work twice. So every creation, update and deletion carries an Idempotency-Key, and the platform does the work once.

POST /core/v1/webhook-endpoints
Idempotency-Key: 6f1c2a52-4f3d-4c53-9a3e-1b8f0d6a7c11

• Choose one key per logical operation (a UUID is fine). Generate it on your side, before the first attempt, and reuse it on every retry: only you know whether two requests are a retry or two intentions. The SDK does this for you.
• The same key with the same request within 24 hours returns the first response (with the header Idempotent-Replayed: true) and does nothing more. A webhook endpoint created twice by mistake never exists twice.
• The same key with a different request is refused: 422 IDEMPOTENCY_BODY_MISMATCH. A new operation needs a new key.
• The same key while the first request is still running waits briefly, then answers 409 IDEMPOTENCY_IN_PROGRESS: retry with the same key.
• A request without the header is refused: 400 IDEMPOTENCY_KEY_MISSING.

Secrets are never stored in clear

Some responses carry a secret you must keep (the whsec_... of an endpoint). The platform stores that response sealed (encrypted), not in clear, so a replay returns the same secret and the database never holds it.

On the way in: events are idempotent too

Delivery of an event to you is at least once: after a crash or a timeout, the platform may send the same event again. Every delivery of an event carries the same Trida-Event-Id (and the same id in the body): deduplicate on it. See Webhooks.