Skip to main content

Retries and Idempotency

Successful delivery​

MiniVoice considers any HTTP response from 200 through 299 successful. Return a success response after safely accepting the event. Keep the endpoint fast and move long-running CRM, ticketing, or analytics work to your own asynchronous processing.

Automatic retry​

MiniVoice automatically retries:

  • network and timeout failures
  • HTTP 408 Request Timeout
  • HTTP 425 Too Early
  • HTTP 429 Too Many Requests
  • HTTP 5xx responses

Most other HTTP 4xx responses are final and are not retried.

The delay after a failed attempt is:

attempt² × 30 seconds

capped at 15 minutes. For example, failures on attempts 1, 2, and 3 schedule delays of 30, 120, and 270 seconds. The maximum number of attempts is configured for the account, with a platform fallback when no account value is set.

Each automatic retry preserves the event ID, event type, sequence, destination, and exact stored request body. It creates a new attempt ID, increments X-MiniVoice-Attempt, and generates a new timestamp and signature.

Idempotency​

Your webhook endpoint must be idempotent. MiniVoice may retry an event, and a user may manually resend a permanently failed event.

Use the top-level event id as the deduplication key:

receive event
→ verify signature
→ check event.id
→ if already processed, return success
→ otherwise process and persist event.id

Do not use X-MiniVoice-Attempt-ID for business idempotency. Attempt IDs deliberately differ between delivery attempts for the same event.

Sequence and delivery order​

sequence records event-generation order for one call. It starts at 0 and increases for each new logical event. Retries and manual resend do not change it.

HTTP delivery order is not guaranteed: an earlier event may be delayed while a later event succeeds. Sort by sequence when reconstructing a call timeline, while allowing historical events to have no populated sequence.

Manual resend​

When a logical event is permanently failed and the Webhook Inspector reports can_resend: true, a customer can queue a manual resend.

Manual resend:

  • keeps the event ID and type
  • keeps the sequence
  • keeps the original destination
  • keeps the exact stored payload
  • creates a new attempt and attempt ID
  • generates a new timestamp and signature at send time

Only failed events are eligible. MiniVoice revalidates the stored destination and rejects a resend if another attempt is already queued, scheduled, or processing.

Automatic retry versus manual resend​

Automatic retries are scheduled by the delivery worker for retryable failures until the configured attempt limit is reached. Manual resend is an explicit customer action after automatic delivery has ended and the event is eligible in the Inspector.

See Webhook Inspector and Troubleshooting to inspect attempts and resend eligibility.