Create Account
← Back to blog
Tutorial

Webhook Retry and Idempotency Basics

Build a MangoOTP webhook receiver that verifies signatures, acknowledges exactly, processes events idempotently, and handles the bounded retry schedule.

A webhook is a notification, not permission to repeat the business action. The receiver must verify authenticity, recognize an event already handled, and return the documented acknowledgement only after safe processing.

Use a public HTTPS endpoint

Configure an HTTPS URL that is reachable from the internet and dedicated to webhook traffic. Do not use a private address, redirect chain, or endpoint that requires an interactive login.

For Webhook Retry and Idempotency Basics, treat “Use a public HTTPS endpoint” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Verify before processing

Use the active webhook signing secret and documented signature fields. Reject unverifiable requests without changing an order, balance, or account state.

For Webhook Retry and Idempotency Basics, treat “Verify before processing” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Store an idempotency identity

Persist the stable event or business identity before applying side effects. A repeated delivery must return the existing result rather than creating a second action.

For Webhook Retry and Idempotency Basics, treat “Store an idempotency identity” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Acknowledge with exact SUCCESS

MangoOTP treats HTTP 2xx with a body whose trimmed value is exactly SUCCESS as acknowledgement. Other bodies, non-2xx responses, and transport failures are not acknowledgements.

For Webhook Retry and Idempotency Basics, treat “Acknowledge with exact SUCCESS” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Understand the retry schedule

An unacknowledged event can be delivered again after 1, 3, 5, and 15 minutes. There are at most five notification attempts; design capacity and alerts for that bounded sequence.

For Webhook Retry and Idempotency Basics, treat “Understand the retry schedule” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Separate receipt from long work

Validate, record, and enqueue internal processing quickly. Do not keep the HTTP request open while performing slow downstream work that can time out.

For Webhook Retry and Idempotency Basics, treat “Separate receipt from long work” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Observe without leaking secrets

Log the safe event identity, result, attempt number, timing, error class, and traceId. Never log the signing secret, signature material, raw API key, or full sensitive payload.

For Webhook Retry and Idempotency Basics, treat “Observe without leaking secrets” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Respect business event boundaries

Act only on documented SMS-received and approved terminal events. Number allocation or an intermediate review is not a final business notification.

For Webhook Retry and Idempotency Basics, treat “Respect business event boundaries” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Practical checklist

  1. Verify use a public https endpoint, record the result, and continue only when the next action is clear.
  2. Verify verify before processing, record the result, and continue only when the next action is clear.
  3. Verify store an idempotency identity, record the result, and continue only when the next action is clear.
  4. Verify acknowledge with exact success, record the result, and continue only when the next action is clear.
  5. Verify understand the retry schedule, record the result, and continue only when the next action is clear.
  6. Verify separate receipt from long work, record the result, and continue only when the next action is clear.
  7. Verify observe without leaking secrets, record the result, and continue only when the next action is clear.
  8. Verify respect business event boundaries, record the result, and continue only when the next action is clear.

Use the final platform status and account history as the source of truth. Do not share passwords, full verification codes, authentication secrets, access tokens, or API keys in screenshots or support messages. More guidance is available in the MangoOTP Help Center.