System designHard~20 minCore Designs / 5 of 30

Interview question

Design a backend endpoint that receives webhooks from an external provider and updates internal state.

Design a webhook ingestion system

Designs authenticated, replay-resistant webhook intake with durable acknowledgement, idempotent asynchronous processing, ordering policy, and reconciliation.

1Say itAnswer out loud first

2CompareCompare with Core answer

3RefineRefine with Stronger and Advanced

TL;DR

I verify the provider signature against the raw request body and enforce its timestamp or replay window according to the provider contract. Then I persist the provider event id, type, received time, and payload or safe normalized form under a unique constraint before returning success. A worker processes the durable record asynchronously. Duplicate deliveries resolve to the same event, so they do not repeat the business change.

Full answer below

Practice focus

Webhook security, idempotency, durable intake, event ordering, retries, replay, observability, and external-provider behavior.

Answer first

Answer path

Core answer first, then checkpoints toward a stronger answer.

Start
Core answer
Start here. This is the direct spoken answer to practice first.
Why this question matters
A webhook sender controls timing and retries, while the receiver controls verification, durable intake, and processing. A fast response is safe only after the receiver has recorded enough information to recover the event.
I verify the provider signature against the raw request body and enforce its timestamp or replay window according to the provider contract. Then I persist the provider event id, type, received time, and payload or safe normalized form under a unique constraint before returning success. A worker processes the durable record asynchronously. Duplicate deliveries resolve to the same event, so they do not repeat the business change.
Checkpoint
Stronger answer
Optional upgrade with examples, trade-offs, and sharper phrasing.
I separate intake status from business processing: received, processing, processed, ignored, and failed remain visible. I return a success response once durable intake succeeds, because returning an error after persistence invites a harmless retry while returning success before persistence can lose the event. Out-of-order events use provider sequence, resource version, or a fetch-current-state call rather than trusting arrival time. Secrets rotate with overlap, payload size is bounded, and unknown event types are retained or ignored by explicit policy.
Finish
Advanced answer
Optional deeper angle for production judgment and nuance.
In production I document which provider fields are authoritative and how signature verification behaves behind proxies and during secret rotation. Rate limits absorb legitimate bursts without disabling provider authentication, and raw payload access is restricted because webhook bodies often contain sensitive data. Reconciliation compares internal state with the provider for events that were missing, delayed, or ended with an ambiguous external result. Replay tooling keeps the original event identity and records operator intent so idempotency remains effective. Metrics cover verification failures, intake latency, duplicates, processing age, ordering gaps, provider retries, and reconciliation repairs. Failure tests crash after durable intake, after the business update, and before acknowledgement to prove no event is lost and no effect is duplicated.

Review signals

Use these to catch weak phrasing, shallow reasoning, and risky claims.

Common mistakesCandidateCommon mistakesMistakes that weaken the answer or signal shallow understanding.Open details

Details

Parsing or transforming the body before signature verification when the provider signs raw bytes.
Returning success before the event is durably recorded.
Treating arrival order as business order.
Replaying failed events with a new identity that bypasses idempotency.

Red flagsCandidateRed flagsSignals that an interviewer may treat as risky.Open details

Details

Cannot explain provider retry behavior.
Loses events if processing fails after returning 200.
Does not handle out-of-order events.
No way to inspect or reprocess failed webhooks.

Follow-up prompts

Quick interviewer prompts inside this drill.

Follow-up questionsCandidateFollow-up questionsLikely next questions after the main answer.Open details

Details

Treat these as the next interviewer turn. Answer one out loud, then save the gap in your practice notes.

When would you return 200 versus a failure to the provider?
How would you handle duplicate events?
How would you rotate webhook signing secrets?

Continue the section

Next in Core Designs: Idempotent Checkout

Step 6 of 30

Design an idempotent checkout backend

Opening drill

System designHard~20 minCore Designs / 5 of 30

Interview question

Design a backend endpoint that receives webhooks from an external provider and updates internal state.

Design a webhook ingestion system

Designs authenticated, replay-resistant webhook intake with durable acknowledgement, idempotent asynchronous processing, ordering policy, and reconciliation.

1Say itAnswer out loud first

2CompareCompare with Core answer

3RefineRefine with Stronger and Advanced

TL;DR

Full answer below

Practice focus

Webhook security, idempotency, durable intake, event ordering, retries, replay, observability, and external-provider behavior.

Answer first

Answer path

Core answer first, then checkpoints toward a stronger answer.

Start
Core answer
Start here. This is the direct spoken answer to practice first.
Why this question matters
A webhook sender controls timing and retries, while the receiver controls verification, durable intake, and processing. A fast response is safe only after the receiver has recorded enough information to recover the event.
I verify the provider signature against the raw request body and enforce its timestamp or replay window according to the provider contract. Then I persist the provider event id, type, received time, and payload or safe normalized form under a unique constraint before returning success. A worker processes the durable record asynchronously. Duplicate deliveries resolve to the same event, so they do not repeat the business change.
Checkpoint
Stronger answer
Optional upgrade with examples, trade-offs, and sharper phrasing.
I separate intake status from business processing: received, processing, processed, ignored, and failed remain visible. I return a success response once durable intake succeeds, because returning an error after persistence invites a harmless retry while returning success before persistence can lose the event. Out-of-order events use provider sequence, resource version, or a fetch-current-state call rather than trusting arrival time. Secrets rotate with overlap, payload size is bounded, and unknown event types are retained or ignored by explicit policy.
Finish
Advanced answer
Optional deeper angle for production judgment and nuance.
In production I document which provider fields are authoritative and how signature verification behaves behind proxies and during secret rotation. Rate limits absorb legitimate bursts without disabling provider authentication, and raw payload access is restricted because webhook bodies often contain sensitive data. Reconciliation compares internal state with the provider for events that were missing, delayed, or ended with an ambiguous external result. Replay tooling keeps the original event identity and records operator intent so idempotency remains effective. Metrics cover verification failures, intake latency, duplicates, processing age, ordering gaps, provider retries, and reconciliation repairs. Failure tests crash after durable intake, after the business update, and before acknowledgement to prove no event is lost and no effect is duplicated.

Review signals

Use these to catch weak phrasing, shallow reasoning, and risky claims.

Common mistakesCandidateCommon mistakesMistakes that weaken the answer or signal shallow understanding.Open details

Details

Parsing or transforming the body before signature verification when the provider signs raw bytes.
Returning success before the event is durably recorded.
Treating arrival order as business order.
Replaying failed events with a new identity that bypasses idempotency.

Red flagsCandidateRed flagsSignals that an interviewer may treat as risky.Open details

Details

Cannot explain provider retry behavior.
Loses events if processing fails after returning 200.
Does not handle out-of-order events.
No way to inspect or reprocess failed webhooks.

Follow-up prompts

Quick interviewer prompts inside this drill.

Follow-up questionsCandidateFollow-up questionsLikely next questions after the main answer.Open details

Details

Treat these as the next interviewer turn. Answer one out loud, then save the gap in your practice notes.

When would you return 200 versus a failure to the provider?
How would you handle duplicate events?
How would you rotate webhook signing secrets?

Continue the section

Next in Core Designs: Idempotent Checkout

Step 6 of 30

Design an idempotent checkout backend

Design a backend endpoint that receives webhooks from an external provider and updates internal state.

Practice focus

Answer path

Why this question matters

Review signals

Follow-up prompts

Continue the section

Design a backend endpoint that receives webhooks from an external provider and updates internal state.

Practice focus

Answer path

Why this question matters

Review signals

Follow-up prompts

Continue the section