Webhook Relay

410 Gone: what it means, 410 vs 404, and webhooks

410 Gone means the resource used to exist at this URL, was removed on purpose, and won't be back. It's a deliberate, permanent statement, stronger than 404 Not Found, which only says nothing is there right now. Clients, crawlers and webhook senders can take a 410 as permission to stop asking.

HTTP/1.1 410 Gone
Content-Type: application/json

{"error": "gone", "message": "This endpoint was removed when the integration was uninstalled"}

410 vs 404

404 Not Found410 Gone
MeaningNothing here nowIt was here, it was removed, it won't return
Permanent?UnknownYes
Search enginesDrop the URL after recrawlsDrop the URL, possibly a little faster
Webhook sendersUsually retry, then give upOften stop and disable the endpoint

If the content moved rather than disappeared, neither is right. Use a 301 or 308 redirect to the new location.

Common reasons you see a 410

  • Deleted content. A product, post or account was removed and the site says so explicitly.
  • Retired API versions. Some APIs answer 410 on endpoints from a sunset version, often with a link to the migration guide.
  • Expired links. One-time download links, invite links and signed URLs past their expiry.
  • Removed webhook receivers. An integration was uninstalled and its endpoint now tells senders to stop.

How to fix a 410

As a visitor: the page was intentionally removed. Search the site for the new location, or check the Wayback Machine for the old content.

As a developer calling an API: read the response body and headers for a pointer to the replacement (a Link header or a docs URL), then migrate. Retrying a 410 won't change the answer.

As a site owner: make sure you meant it. A misconfigured rewrite rule that returns 410 for live pages will get them dropped from search results. Check with curl -I https://example.com/path/.

410 on a webhook endpoint

For webhooks, 410 carries a specific meaning: "stop sending to this URL." Many senders treat it differently from every other error. Rather than retrying with backoff, they fail the delivery immediately and disable or unsubscribe the endpoint.

That makes 410 useful, and dangerous:

  • Useful: when a customer uninstalls your app or deletes an integration, answering 410 cleans up the subscription on the sender's side without anyone touching a dashboard.
  • Dangerous: a catch-all route that returns 410 for unknown paths, or a framework default during a deploy, can silently unsubscribe a live integration. Use 503 for temporary downtime, and 200 for event types you choose to ignore.

If you send webhooks to your own customers, you need a policy for this. Webhook Relay outbound webhooks handle it as follows:

  • A 410 Gone response fails that delivery for good and disables the endpoint. Other errors and timeouts are retried on a backoff schedule.
  • After 5 failed attempts in a row, an endpoint is marked failing. With auto_disable on, it's disabled after 100 failed attempts in a row spanning at least 12 hours.
  • Resuming a disabled endpoint reactivates it. Messages skipped while it was disabled aren't sent automatically; you replay them once the endpoint is ready.

See retries and endpoint states for the full table.

When to return 410 from your own API

Return 410 when you have deliberately and permanently removed a resource and want clients to stop requesting it: a deleted record you keep a tombstone for, a sunset API version, an uninstalled integration's webhook URL. If you don't know whether something ever existed, return 404. If it moved, redirect.

Frequently asked questions

What does 410 Gone mean?

HTTP 410 Gone means the resource used to exist at this URL, was removed deliberately, and isn't coming back. There is no forwarding address. It's a stronger, more specific statement than 404 Not Found, which only says nothing is there right now.

What is the difference between 404 and 410?

404 Not Found means the server can't find the resource and makes no promise about whether it existed or will return. 410 Gone means it existed and was removed permanently. Clients and crawlers can stop requesting a 410 URL; a 404 might be worth checking again.

Is 410 better than 404 for SEO?

Google treats both as signals to drop a URL from the index, and has said a 410 may be processed slightly faster. The difference is small. If the content has moved, use a 301 or 308 redirect to the new URL instead of either one.

What happens when a webhook endpoint returns 410?

Many webhook senders treat 410 Gone as an instruction to stop. Instead of retrying, they mark the delivery failed and disable or unsubscribe the endpoint. Webhook Relay outbound webhooks do this: a 410 stops retries for that delivery and disables the endpoint until someone resumes it.

Should I return 410 from my webhook endpoint?

Only when you want the sender to stop sending to that URL permanently, for example after a customer uninstalls your integration. Don't return 410 during maintenance or for unknown event types. Use 503 for temporary downtime and 200 for events you simply ignore.

Related