Delivery guarantees

Actions can cross service boundaries and reach your webhook endpoint more than once. Tanitar keeps those actions durable, but your integration must handle retries safely.

The contractCopy Anchor Link

• A committed action is not silently lost. State changes and their outgoing messages are stored together.
• Delivery is at least once. A temporary failure can produce another delivery of the same message.
• The message id is stable. Use it to recognize a delivery you have already accepted.
• Retries are bounded. Repeated failures end in a recoverable dead-letter record instead of an infinite retry loop.
• Recovery preserves identity. Replaying a message keeps its original message id, so existing deduplication still works.

Webhook receiver rulesCopy Anchor Link

For every webhook delivery:

1. Verify the signature against the raw request body.
2. Reject a timestamp outside the allowed five-minute window.
3. Check whether webhook-id was already accepted.
4. Store the id and the work atomically when possible.
5. Return a success only after the delivery is safe to process.

If processing happens asynchronously, acknowledge after placing the delivery in your own durable queue. See Verifying signatures and Retries.

Retrying API callsCopy Anchor Link

Routes that require Idempotency-Key return the original completed outcome when the same key and body are sent again. Reusing a key with a different request returns 409. Keep one key per logical operation and retain it until the operation has a final outcome. See Idempotency.

RecoveryCopy Anchor Link

When a message exhausts its retries, use the dashboard Recovery page or the recovery API. For example, list failures with GET /platform/recovery/dead-letters and replay one with POST /platform/recovery/dead-letters/:deadLetterId/replay. These operations require messaging:read and messaging:replay respectively.

Before replaying, correct the cause and check whether the destination already applied the original message. See Dead-letter recovery for the full workflow.

Domain outcomesCopy Anchor Link

A rejected grant or shop purchase is a recorded outcome, not a missing delivery. Read its status and reason instead of retrying until it succeeds. The detailed state and recovery rules live in Rewards, Shop and the event catalog.