HTTP Status Codes in Respond to Webhook

I learned this the hard way after a “successful” webhook kept retrying for hours and quietly created duplicate records in a U.S. SaaS pipeline.

HTTP Status Codes in Respond to Webhook is how you tell the sender exactly what happened—so retries, alerts, and downstream automations behave the way you intended.

Why webhook status codes decide whether you get retries or duplicates

Most webhook providers treat your response as a contract: a 2xx means “accepted,” while many 4xx/5xx codes mean “try again later” (or “stop and alert,” depending on the platform). If you return the wrong code, you can trigger:

Unwanted retries that flood your endpoint and inflate API usage.
Duplicate processing when the sender replays the same event.
Silent drops when you return 2xx but didn’t actually process the data.
Security gaps when invalid signatures still get a 200.

The webhook response rule you can rely on

Return 2xx only when you intentionally accept the event. “Accept” can mean processed now, queued for later, or safely ignored as a duplicate.
Use 4xx for caller mistakes (bad payload, missing auth, unsupported media type). Many senders will stop retrying or move to a dead-letter flow.
Use 5xx for your server/provider failures (temporary outage, dependency down). Many senders will retry.

Webhook-friendly HTTP status codes (practical table)

Status code	When to return it in a webhook	What it usually triggers
200 OK	Processed successfully and no further action is needed.	Sender stops retries.
201 Created	You created a new resource (rare for webhooks, but valid if you do).	Sender stops retries.
202 Accepted	You validated the event and queued it for async processing.	Sender stops retries (commonly).
204 No Content	Processed successfully and you want an empty body.	Sender stops retries.
400 Bad Request	Malformed JSON, missing required fields, invalid schema.	Sender may stop or alert (platform-dependent).
401 Unauthorized	Missing/invalid auth header, failed signature check.	Often stops; may alert.
403 Forbidden	Auth is valid but not allowed (wrong tenant, blocked source).	Often stops; may alert.
404 Not Found	Wrong URL or disabled endpoint (use carefully; can hide mistakes).	Often stops; sometimes retries briefly.
409 Conflict	Duplicate event or version conflict you intentionally detected.	Sender may stop; good for dedupe signals.
410 Gone	Endpoint intentionally retired and should not be used again.	Usually stops permanently.
415 Unsupported Media Type	Sender posted a content type you don’t accept (not application/json).	Often stops; may alert.
422 Unprocessable Entity	JSON is valid, but business rules fail (invalid state, missing mapping).	Often stops; good for validation feedback.
429 Too Many Requests	You are rate-limited; ask sender to slow down (ideally with Retry-After).	Often retries later.
500 Internal Server Error	Unexpected server exception; temporary failure.	Often retries.
502 Bad Gateway	Upstream dependency failed (proxy, gateway, edge function).	Often retries.
503 Service Unavailable	Service is down or overloaded; temporary.	Often retries (best with Retry-After).
504 Gateway Timeout	Dependency timed out; you can’t confirm processing.	Often retries (risk of duplicates).

The biggest production mistake: returning 200 before you’re safe

If you return 200 while your workflow still might fail, you’re choosing silent data loss over retries. If you return 500 too often, you’re choosing duplicate risk and traffic spikes. The best balance is usually:

Validate fast (auth/signature, JSON shape, required fields).
Decide acceptance (accept, reject, or accept-and-queue).
Respond quickly with 202 if heavy work is asynchronous.
Make processing idempotent so retries are safe.

What to return when you queue work asynchronously

When the sender expects a quick acknowledgment (common in U.S. SaaS webhooks), return 202 Accepted after you verify the request and store the event for later processing. This avoids timeouts and reduces repeated delivery attempts.

HTTP/1.1 202 Accepted

Content-Type: application/json

{"accepted": true, "queued": true, "message": "Event validated and queued"}

Deduplication: how 409 can be your “safe stop” signal

Retries are normal. The fix is not “try to avoid retries,” but “make retries harmless.” Store a unique event ID (or a hash of payload + timestamp window) and treat repeats as duplicates. If the event is already processed, you can safely return 200 or 409. Many teams prefer returning 200 for duplicates to stop delivery loops, while keeping the dedupe evidence in logs and metrics.

// Pseudocode

if (!signatureValid) return 401

if (!payloadValid) return 400

eventId = getEventId(payload)

if (seenBefore(eventId)) return 200  // or 409 if your provider handles it cleanly

enqueue(eventId, payload)

return 202

Security responses: 401 vs 403 (and why it matters)

401 Unauthorized fits when the request fails authentication (missing/invalid signature, token, or secret).
403 Forbidden fits when authentication is valid but the action is not allowed (blocked workspace, wrong tenant, restricted IP).

A real-world weakness: signature verification often fails because of raw body handling (some frameworks parse JSON and change whitespace/ordering). The fix is to verify the signature against the raw request body before JSON parsing, then parse after verification.

Timeouts and 504: the fastest way to create duplicates

If your endpoint times out, the sender may retry because it never received a clear acknowledgment. If your system actually processed the event right after the timeout, you now have two deliveries racing each other. Prevent this by:

Returning 202 quickly and processing async.
Using idempotency keys (event ID) to block duplicates.
Recording a “received” marker before doing slow work.

Using n8n: what “Respond to Webhook” should return in common scenarios

If you’re using n8n for webhook-driven automations, the Respond to Webhook node is where status codes become operational behavior. You can explore official documentation here: n8n Documentation.

A real weakness you’ll hit: workflows that call multiple APIs (CRM + email + database) can exceed typical webhook time budgets. The fix is to respond early with 202 and push the heavy work into background steps (or a queued workflow), while storing an event ID so retries don’t duplicate updates.

n8n "Respond to Webhook" suggestions

- Success immediately: 204 (empty) or 200 (with JSON)

- Validated + queued: 202 (JSON: {"queued": true})

- Invalid signature: 401

- Missing required field: 422 (JSON: {"error":"missing_field","field":"email"})

- Temporary dependency down: 503 (add Retry-After header if supported)

If you use Zapier or Make: handle “replay” like it’s guaranteed

Many teams connect webhooks to automation platforms like Zapier or Make to move faster. The upside is speed; the downside is you can accidentally create a retry storm when a downstream step fails.

A real weakness: these platforms can re-run steps or receive the same webhook again when there’s a transient error, which can duplicate actions like “create contact” or “send email.” The fix is to design your flow with a dedupe gate (event ID storage) and to favor “upsert” operations where possible instead of “create.”

Returning 429 correctly (without breaking senders)

Use 429 Too Many Requests only when you truly need the sender to back off. If you can accept the event and queue it, 202 is usually a better user experience. If you do return 429, include Retry-After when your stack supports it, and keep your body short and structured.

HTTP/1.1 429 Too Many Requests

Retry-After: 30

Content-Type: application/json

{"error":"rate_limited","retry_after_seconds":30}

Clear error bodies that don’t leak sensitive data

Keep webhook responses short. If the sender logs your body (many do), don’t echo secrets, full payloads, or internal stack traces. A good pattern is a compact error code, a human-readable message, and a request ID you can search in logs.

{"error":"invalid_signature","message":"Signature verification failed","request_id":"req_7f3b2"}

FAQ: webhook status codes that engineers actually search for

Should you return 200 or 204 for a webhook?

Return 204 when you want an empty body and you’re confident the sender doesn’t need a response payload. Return 200 when you want to include JSON (like a request ID or a queued flag). Both are valid “success” acknowledgments.

When is 202 Accepted better than 200 OK?

Use 202 when you validated the request and accepted it for processing, but the work will finish later. This prevents timeouts and reduces retries when your workflow needs database writes, third-party API calls, or multiple steps.

What status code stops webhook retries?

In many webhook systems, any 2xx stops retries. Some platforms treat certain 4xx as terminal errors too, but you should not depend on that unless your provider documents it. If you want retries to stop reliably, return 2xx after you’re safe (processed or queued).

Should duplicates return 409 Conflict?

409 can be a clean signal that you detected a duplicate or a conflicting state. In practice, returning 200 for duplicates is often safer if you want to guarantee the sender stops delivery loops. Choose one approach, document it internally, and keep your dedupe logic the real source of truth.

What do you return when your database is down?

Return 503 when the failure is temporary and you want the sender to retry later. If you can accept the event and store it somewhere durable (queue/log) even while the database is down, return 202 and process it after recovery.

Is 400 or 422 better for invalid payloads?

Use 400 when the payload is malformed (bad JSON, invalid types, missing basic structure). Use 422 when the JSON is valid but fails business validation (missing required business field, invalid state transition, unsupported event type).

How do you test webhook responses quickly?

Post test events using curl or a client like Postman, then verify your endpoint returns the intended status codes under success, validation failure, auth failure, and dependency failure conditions.

A real weakness: tests often cover only the happy path. The fix is to simulate failure modes—timeouts, invalid signatures, duplicate event IDs, and temporary 503 responses—so you can see exactly how the sender retries.

Conclusion: make your status code strategy boring and predictable

When your webhook responses are consistent, everything downstream becomes easier: retries become safe, duplicates become rare, and production incidents become explainable. Lock in a small set of codes (2xx for accepted, 4xx for caller faults, 5xx for temporary server faults), add deduplication, and return fast—your automations will feel dramatically more reliable.

Toolient