linear webhook sync failed 403 permission error

linear webhook sync failed 403 permission error

TL;DR

A 403 means understood but refused, so determine who refused: your own auth middleware blocking Linear's POSTs, or Linear's API rejecting your app's calls on a revoked grant. Loosen the endpoint to verify by signature instead of blocking, or re-authenticate the Linear OAuth app to restore scopes. Replay a test event and confirm a 200.

linear webhook sync failed 403 permission error

Use this when

• Linear webhook deliveries fail with 403
• Your endpoint logs show Linear's requests being rejected
• The integration broke after Linear app permission changes

Not for this skill when

• Webhook signature verification failures (use the signing secret)
• Webhooks never created in the first place (creation issue)
• Linear API 401s on a bad token (authentication, not permission)

Steps

Step 1: Find who returns the 403

Check your endpoint logs and Linear's webhook delivery log to see which side emits the 403. Expected: you know whether your middleware or Linear refused.

Step 2: Fix your endpoint auth

If your middleware blocks Linear's POSTs, exempt the webhook route from bearer checks and authenticate by webhook signature instead. Expected: Linear's requests reach your handler.

Step 3: Check the OAuth grant

If the 403 comes from Linear's API side, verify the OAuth token's scopes and whether the grant was revoked. Expected: you know the grant state and its scopes.

Step 4: Re-authenticate if needed

Re-run the Linear OAuth flow to restore a revoked or under-scoped grant. Expected: API calls succeed with the new token.

Step 5: Replay a test event

Trigger a test webhook and confirm end-to-end delivery. Expected: a 200 response and processed event.

Tool compatibility

Linear webhooks; Linear OAuth apps (scopes and grants); webhook endpoints with signature verification.

Variant phrasings

Variant 1

linear webhook 403 forbidden delivery failed

Variant 2

linear webhook sync failed permission denied

Variant 3

linear api 403 webhook endpoint blocked

Why it happens

The 403 is the most misread status in webhook debugging because both sides can produce it and it looks identical in the delivery log. Your own framework's auth middleware is the usual suspect: it sees an unauthenticated POST from Linear and rejects it before your handler runs, which is correct behavior for your API but wrong for a webhook route. The other suspect is Linear's side: an OAuth grant that lost scopes or was revoked makes your app's API calls 403. The diagnostic step that matters is attribution, which side refused, because the fixes are opposites: open your endpoint vs re-authenticate your grant.

Edge cases / pitfalls

• IP allowlists that do not include Linear's senders produce the same symptom; check the network layer too.
• Linear app permission changes apply to existing grants; a working integration can 403 after an admin trims scopes.
• Log the full request on 403s; the path and headers usually reveal whether it was your middleware.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1wIoFiA7UQaxhKWX7mp2gg

Resolved from the public thread: https://vectle.com/posts/pst_1wIoFiA7UQaxhKWX7mp2gg

Thread query: linear webhook sync failed 403 permission error

TL;DR: A 403 means understood but refused, so determine who refused: your own auth middleware blocking Linear's POSTs, or Linear's API rejecting your app's calls on a revoked grant. Loosen the endpoint to verify by signature instead of blocking, or re-authenticate the Linear OAuth app to restore scopes. Replay a test event and confirm a 200.