Linear webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems Linear webhooks cause in production and how to handle each one. What Linear sends and how it's signed is on the Linear webhooks overview, every event type is on Linear webhook events, and signature verification code is on Verify Linear webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return exactly 200 within 5 seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Record Linear-Delivery; compare data.id and data.updatedAt; make handlers idempotent | Drops repeats before they reach your handler |
| Ordering | Compare data.updatedAt; fetch current state when in doubt | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Stay available; re-enable a disabled webhook; reconcile from the GraphQL API | Accepts deliveries while your service is down and replays them |
| Choosing events | Subscribe only to the resource types you process; check type and action | Filters and routes events by header or body |
| Testing | Forward events to localhost through a public URL | Forwards to localhost and replays past events |
| Other limits | Plan for the one-minute timestamp check, immediate secret rotation and admin-only setup | Holds events in a queue and delivers them at a rate you set |
Linear webhook timeouts and slow handlers
Return HTTP 200 within 5 seconds, then do the work in a background job.
Why it happens: Linear treats a delivery as failed if your server is unavailable, takes longer than 5 seconds to respond, or responds with any status other than 200. That includes success codes such as 201 or 204, so a handler that does its job and returns one of those still gets retried. A handler that calls other APIs before responding can go over the limit.
Fix it in your handler:
- Verify the signature and return 200 straight away, with that status and no other.
- Push the event onto a queue and process it in a worker. See why to process webhooks asynchronously.
- For an agent, send your first activity separately. Linear expects a response to the webhook within 5 seconds, and a first activity within 10 seconds of a
createdevent, or it shows the agent as unresponsive.
With Event Gateway: Hookdeck accepts each Linear delivery immediately, then queues events and delivers them to your service at a rate you set, with its own retries. Your handler can take as long as it needs without failing a Linear delivery.
Duplicate Linear webhooks
A retry can repeat work your handler has already done. Record Linear-Delivery and check the entity's own fields as well.
Why it happens: If your handler finishes the work but responds late, or with a status other than 200, Linear counts the delivery as failed and sends it again. Linear-Delivery is a UUID that identifies the payload, but Linear's docs don't say whether a retry keeps the same value. webhookId won't help, because it identifies the webhook and not the delivery. The signature proves where a request came from, not that it's the first copy.
Fix it in your handler:
- Track processed
Linear-Deliveryvalues, using a database table with a unique constraint. - Make every handler idempotent: the same result however many times it runs. On data change events,
type,action,data.idanddata.updatedAttogether describe one change. - Wrap the side effect and the record of it in one transaction.
With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.
Out-of-order Linear webhooks
Linear's docs make no promise about delivery order. Compare data.updatedAt with what you've stored when order matters.
Why it happens: Retries run on a delay of up to hours, so an event that failed once can arrive well after newer events for the same entity. An older update applied last would overwrite newer data. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Store each entity's
updatedAt, and don't let an event with an older value overwrite newer state. - Use
updatedFromto see which properties anupdatechanged, rather than assuming the whole object is new. - When an event is ambiguous, fetch the entity's current state from Linear's GraphQL API.
- Handle a
removefor an entity you've never seen, and anupdatethat arrives before itscreate.
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
Linear webhook retries and disabled webhooks
Linear retries a failed delivery 3 times, after 1 minute, 1 hour and finally 6 hours. A webhook that stays unresponsive might then be disabled.
Why it happens: If the URL keeps failing, Linear can turn the webhook off, and it has to be re-enabled manually. Its docs give no threshold, and they describe no way to resend a delivery, so an outage longer than the retry schedule leaves a gap you have to fill yourself. While a webhook is disabled, nothing is delivered.
Fix it in your handler:
- Run the endpoint on high-availability infrastructure, and return a 500 for a real failure so that Linear retries.
- Check the webhook's
enabledfield with the GraphQL API on a schedule, and alert when it's false. Turn it back on from settings or withwebhookUpdate. - After an outage, query the GraphQL API for what changed in the gap.
With Event Gateway: Hookdeck captures every Linear delivery while your services are down, so Linear's deliveries succeed and the webhook stays enabled. Failed events can be retried automatically, manually or in bulk once you recover.
Choosing which Linear events to listen to
Subscribe each webhook only to the resource types your integration processes, and limit it to one team where you can.
Why it matters: A webhook covers either one team or all public teams, and every extra resource type is a request your server has to accept, verify and discard. The full list, with sample payloads where Linear publishes them, is on Linear webhook events. Some categories change what users see: once an OAuth app subscribes to AgentSessionEvent, Linear shows Agent Session UI to its customers, even if you only wanted to look at the events.
Fix it in your handler:
- List the resource types your code handles, and set exactly those in
resourceTypeswhen you callwebhookCreate, or in settings. - Check
typeandactiontogether. Data change events usecreate,updateandremove, butIssueSLAusesset,highRiskandbreached, andOAuthAppusesrevoked. - Read the right field for the stream.
IssueSLAputs the issue inissueDataandAgentSessionEventusesagentSession, so code that expectsdatafinds nothing. - Ignore types your handler doesn't expect, and still return 200, because new ones can appear.
With Event Gateway: Hookdeck filters and routes events by header or body, so one Linear webhook can feed several services. See how to build a Linear agent for routing agent events.
Testing and debugging Linear webhooks locally
Forward real Linear events to your local server through a public URL rather than deploying to test.
Why it happens: Linear requires a publicly accessible HTTPS URL that isn't localhost. Its docs describe no CLI for forwarding events and no test delivery, so you trigger an event by making the change in Linear, such as commenting on an issue.
Fix it in your handler:
- Use a tunnel or a forwarding tool to get a public URL for your local server.
- Keep fixtures of real payloads for edge cases. Linear publishes few full examples, so save your own, and start from the samples on Linear webhook events.
- Test signature verification with the real signing secret in every environment, not only locally.
With Event Gateway: The Hookdeck CLI gives you a stable URL that sends webhooks to your machine: run hookdeck listen 3000 linear --path /webhooks/linear, then replay past events with one click. See how to run Claude Code as a Linear agent for a full example.
Other Linear webhook limits
Plan for the timestamp check, secret rotation and who can manage webhooks before they reach production.
The one-minute timestamp check. Linear recommends rejecting a delivery whose webhookTimestamp is more than a minute from when your system sees it, and it's in milliseconds, so comparing it with a clock in seconds rejects everything. Make the check when the request arrives, because a worker behind a queue can see a real delivery that's already over a minute old. Keep server clocks in sync with NTP. Use the body field rather than the Linear-Timestamp header, because only the body is signed. The code is on Verify Linear webhooks.
Secret rotation has no overlap. Rotating a signing secret takes effect immediately, so deliveries fail verification until your handler has the new one. Update both at the same moment, and expect some deliveries to fail and be retried.
Admins only. Only workspace admins, or OAuth apps with the admin scope, can create or read webhooks. A scheduled job that checks enabled needs one of those.
Private teams. A webhook set to all public teams doesn't cover private ones. The alternative Linear's docs describe is a webhook for a single team.
IP allow lists. Linear publishes its outbound addresses on its security page and as JSON, and aims to update the file four weeks before using a new address. Use a list as well as the signature check.
With Event Gateway: Hookdeck gives Linear one stable URL to deliver to, absorbs bursts in its queue, and delivers to as many destinations as you need at a rate you configure.
Keep a slow handler from getting your Linear webhook disabled.
Hookdeck Event Gateway accepts every Linear delivery, verifies its signature, queues events and retries to your service on your schedule.