Delivery semantics

Notification delivery is at-least-once. Tekmerion makes no exactly-once and no ordering guarantee on the webhook surface. A receiving endpoint MUST be safe under duplicate, delayed, and out-of-order delivery.

At-least-once

The same notification MAY arrive more than once. Each delivery and each retry of one notification is a separate send of the same record, carrying the same delivery_record_id.

Receivers MUST deduplicate by delivery_record_id.
Retries are safe by construction: a retry repeats an existing notification; it does not create a new one. Acting on the same delivery_record_id twice MUST be a no-op on the second occurrence.

No ordering

Notifications MAY arrive in any order.

A payment_finalized notification MAY arrive before, or without, the corresponding payment_observed. Finalized notifications remain valid regardless of whether the observed notification was delivered, delayed, or missed.
An older retry MAY arrive after a newer delivery.
Receivers MUST NOT infer canonical payment state from delivery order.

Acknowledgement and retry

The receiving endpoint acknowledges receipt by returning a success response. Any non-success response, timeout, or connection error is treated as a failed attempt, and the notification is retried as a new send of the same record. A failed delivery attempt affects only delivery bookkeeping; it is never payment truth.

Endpoints MUST respond promptly and idempotently. Do not perform slow downstream work inline before acknowledging — accept, deduplicate, and process asynchronously.

A notification is not the truth

A webhook is a side effect of a payment event, not the authoritative record of it. Receipt — or absence — of a notification is not settlement truth.

Reconcile canonical state through the API and the signed Proof-of-Payment artifact.
Never gate fulfilment solely on having received a webhook; a missed or delayed notification does not mean the event did not occur, and a received notification is a delivery-plane signal, not proof.
A failed notification delivery MUST NOT be read as a failed payment.

Receiver checklist

Verify the signature before processing — see Signature verification.
Deduplicate by delivery_record_id.
Treat unordered receipt as normal; correlate by payment_intent_id.
Acknowledge fast; process asynchronously.
Reconcile against the API / Proof-of-Payment rather than trusting the webhook as truth.