Open a DueReason approval request when a Linear issue changes state
Move a Linear issue into a workflow state you configure and DueReason opens a signed approval request automatically, with no polling loop or custom script.
Updated · 7 min read
In short
- An inbound Linear endpoint maps one team and one workflow state to one DueReason action: move an issue in that team into that state and a real approval request opens, with a signed grant and a ledger entry behind it, not just a notification.
- Setup is two steps in opposite directions: create the endpoint in DueReason's console first to get a URL, then paste that URL and your own webhook secret into Linear's own webhook settings (Settings > API > Webhooks).
- A payload template maps Linear's event fields onto the action's own payload with `{{data.title}}`-style placeholders, so the request DueReason opens carries real data, not just a link back to Linear.
- Only an Issue event whose action is `update`, whose state actually changed on that delivery, and whose new team and state name match the endpoint's configuration opens a request -- editing a title, adding a comment, or an issue merely sitting in the target state is silently ignored.
- GitHub is the other source on the same shape: a configured repository and label, instead of a team and target state, opens the request when that label is added. A console-only `custom` source also exists for wiring up any other system's webhook.
Moving an issue into a Done, Ready for release or Needs budget column is already how a lot of engineering teams flag "this is finished, someone has to sign off" -- the state itself carries the decision point, long before anyone writes it down anywhere else. An inbound Linear endpoint turns that state transition into a real DueReason approval request the moment it happens, with a signed grant and a ledger entry behind the decision, instead of a Slack ping someone has to remember to act on.
What actually happens
Each inbound endpoint ties one Linear team (by its team key, e.g. ENG) and one workflow state name (e.g. Done) to one DueReason action. The moment an issue in that team moves into that state, DueReason opens a request against the action you chose, pre-filled from the event: a title such as Linear: ENG issue moved to "Done", a reason naming the issue and linking back to it in Linear, and whatever payload fields your template maps from the event. From there it is a normal DueReason request -- it goes through the action's own workflow, routes to the approvers you configured, and produces the same signed, single-use grant any other request does.
Set it up in DueReason first
In Settings > Inbound webhooks, Add endpoint with source Linear asks for four things: Team key (the Linear team key, e.g. ENG), Target state (the exact workflow state name that opens a request when an issue moves into it, e.g. Done), Action (which DueReason action the request opens against, picked from your organization's configured actions), and a Payload template -- JSON mapping that action's payload fields to Linear event data, for example { "title": "{{data.title}}", "url": "{{url}}" }. You also paste in a Linear webhook signing secret here: a value *you* generate, not one DueReason issues -- you'll paste the exact same value into Linear a moment later, and DueReason never shows it again after this step.
Creating the endpoint hands you back one webhook URL on your own domain, shaped /api/webhooks/linear-inbound/{endpointId}. Nothing fires until that URL is registered on Linear's side.
Then point Linear at it
In Linear's own Settings > API > Webhooks, add a webhook with that URL, select the Issues event, and paste the same secret you just entered into DueReason as the webhook's signing secret. From here, Linear signs every delivery to that URL with your secret, and DueReason's endpoint verifies that signature -- the Linear-Signature header, HMAC-SHA256 over the exact raw request body, hex-encoded with no prefix (unlike GitHub's sha256=...) -- before it looks at anything else in the payload. An endpoint with no matching secret, or a request that didn't come from Linear at all, is rejected before the team or state is even read.
What matches, and what's quietly ignored
Several things all have to line up for a delivery to open a request: the Linear event type has to be Issue, its action field has to be exactly update, and -- unlike simply checking the issue's current state -- the delivery's own updatedFrom has to actually carry a stateId, meaning the workflow state changed on *this* delivery rather than some unrelated field (a title edit, say) on an issue that already happens to sit in the target state. On top of that, the event's team key and new state name have to match what the endpoint was configured with. None of that is an error state: a delivery that doesn't match any of it is simply a no-op, and DueReason still answers Linear with success so the delivery isn't retried. The one case that does fail outright is a delivery whose signature doesn't check out, or a URL with no matching endpoint at all -- those come back as real HTTP errors.
Retries are handled too: a resent delivery carries the same Linear-Delivery header every time (the route rejects a delivery with that header missing outright), and DueReason records that id against the endpoint before it does anything else, so a resend of a delivery already acted on is recognized as the same event and answered without opening a second request.
Mapping Linear's fields into the request
The payload template is plain JSON with {{dot.path}} placeholders resolved against the event DueReason received: data.* for the issue itself (id, title, and whatever other fields Linear's payload carries), plus team.* and state.* for the issue's new team and state, actor.* for who made the change, and a top-level url for the link back to the issue in Linear. A field that is *only* one placeholder keeps that field's own type rather than being stringified, exactly like the GitHub source; a path the event doesn't actually have resolves to null rather than breaking the delivery, and what actually gates the request is still the target action's own payload schema -- a template that maps a required field to a path the event never carries fails the same validation a manually-filed request with a missing field would.
Why this is a request, not a notification
A Slack message triggered by a Linear state change tells someone a decision is needed; it does not produce anything that records who decided, under what workflow, or that can be checked again later. Because this opens a real DueReason request, the usual workflow applies in full -- routing to the right approver group, requiring a written reason where the action demands one, producing a signed grant once it's answered -- and the request, its decision and its grant all sit on the same hash-chained ledger as a request filed from the console or the API. The no-code webhook recipe covers the opposite direction -- reacting to DueReason's own approval.approved event once a request like this is decided -- if you want to wire what happens *after* the approval, too. The equivalent GitHub-side setup is covered in the GitHub issue/PR guide: same shape, a labeled issue or pull request in place of a state transition.
What's not here yet
The console's "send a sample event" preview, available for the GitHub and custom sources, is not available for Linear yet -- there is no fixture-based dry run before you wire up a real Linear webhook; the first real delivery is also the first thing you can check in the endpoint's delivery log. Jira is not available today either, and there is no installable Linear integration to add this from Linear's own marketplace -- every endpoint is configured by hand, per organization, in DueReason's own console, against a Linear webhook you set up yourself the same way you would for any other integration.
Questions
- Does editing an issue's title or adding a comment also open a request?
- No. Only an Issue update event whose updatedFrom carries a stateId -- meaning the workflow state actually changed on that delivery -- matches at all, and the new team key and state name then have to match the endpoint's configuration. Any other field edit, a comment, or an issue that already sits in the target state being touched for an unrelated reason is ignored, with no request opened and no error either.
- What if Linear retries a delivery because the first attempt timed out?
- Linear resends the same Linear-Delivery id on a retry, and DueReason records that id against the endpoint before doing anything else, so a retried delivery is recognized as the one already acted on rather than opening a second request.
- Is the webhook secret the same value as DueReason's outbound webhook secret?
- No, and they run in opposite directions. The outbound webhook secret (Settings > Webhooks) is issued by DueReason so you can verify deliveries DueReason sends you. This inbound secret is one you generate yourself and paste into both DueReason and Linear's own Settings > API > Webhooks, so DueReason can verify deliveries Linear sends it.
- Can I wire this up for GitHub or Jira instead of Linear?
- GitHub, yes: pick source GitHub when adding the endpoint and configure a repository and label instead of a team key and target state -- adding that label to an issue or pull request opens the request. Jira is a planned follow-up that would reuse the same shape, not something available to configure now; a generic custom source already covers any other system in the meantime.
- Can I preview what a Linear state change would file before wiring up the real webhook?
- Not yet. The console's "send a sample event" dry run exists for the GitHub and custom sources today, not for Linear, so the first real delivery against your endpoint is also the first one you can inspect, in the endpoint's delivery log.
- What happens if my payload template references a field the event doesn't have?
- The template renders that placeholder as null rather than failing the delivery. The request still opens, but the target action's own payload schema validates it exactly as it would any other request, so a required field mapped to a path the event never carries fails that validation the same way a manually-filed request with a missing field would.
Open your first request from a Linear state change
Add an inbound Linear endpoint in Settings > Inbound webhooks, point Linear's own webhook settings at it, and move an issue into the configured state to see the request appear.
Create your accountSources
This guide explains the regulation as we read it; it is not legal advice. Check the official text and your national law, which may add obligations.