Skip to content

Open a DueReason approval request from a labeled GitHub issue or PR

Add a label to a GitHub issue or pull request and DueReason opens a signed approval request automatically, with no polling loop or custom script.

Updated · 7 min read

In short

  • An inbound GitHub endpoint maps one repository and one label to one DueReason action: add that label to an issue or pull request 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 the repository's GitHub webhook settings.
  • A payload template maps GitHub's event fields onto the action's own payload with `{{issue.title}}`-style placeholders, so the request DueReason opens carries real data, not just a link back to GitHub.
  • GitHub's own delivery id makes a retried delivery a no-op instead of a duplicate request, and only `issues` and `pull_request` events with action `labeled` match at all -- removing a label, commenting or any other event type is silently ignored.
  • Linear and Jira are two more sources on the same shape: a configured team key and target workflow state (Linear), or project key and target status (Jira), opens the request instead of a repo and label. Jira has no HMAC signature header, so its endpoint is authenticated with a shared secret header instead.

Labeling an issue or pull request is already how a lot of teams flag "this needs a decision" -- needs-approval, ship-it, budget-review. An inbound GitHub endpoint turns that label into a real DueReason approval request the moment it is applied, with a signed grant and a ledger entry behind the decision, instead of a bot comment or a Slack ping someone has to remember to act on.

What actually happens

Each inbound endpoint ties one GitHub repository and one label to one DueReason action. The moment someone adds that label to an issue or pull request in that repository, DueReason opens a request against the action you chose, pre-filled from the event: a title such as GitHub: acme/widgets#42 labeled "needs-approval", a reason naming the issue or PR and linking back to it on GitHub, 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 asks for four things: Repository (owner/repo), Label (the exact GitHub label that opens a request when it's added), 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 GitHub event data, for example { "title": "{{issue.title}}", "url": "{{issue.html_url}}" }. You also paste in a GitHub webhook secret here: a value *you* generate, not one DueReason issues -- you'll paste the exact same value into GitHub 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/github-inbound/{endpointId}. Nothing fires until that URL is registered on the GitHub side.

Then point GitHub at it

In the repository's own Settings > Webhooks > Add webhook, paste that URL as the Payload URL, set content type to application/json, and paste the same secret you just entered into DueReason as the webhook's secret. Select the Issues and Pull requests events (or "Send me everything" if you'd rather filter centrally) and save. From here, GitHub signs every delivery to that URL with your secret, and DueReason's endpoint verifies that signature -- X-Hub-Signature-256, HMAC-SHA256 over the exact raw request body -- before it looks at anything else in the payload. An endpoint with no matching secret, or a request that didn't come from GitHub at all, is rejected before the label or repository is even read.

What matches, and what's quietly ignored

Three things all have to line up for a delivery to open a request: the GitHub event type has to be issues or pull_request, its action field has to be exactly labeled (adding a label -- removing one, or any other issue/PR event GitHub sends, does not match), and the event's repository and label 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 GitHub 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: GitHub resends a delivery that times out or errors, carrying the same X-GitHub-Delivery id every time. 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 GitHub's fields into the request

The payload template is plain JSON with {{dot.path}} placeholders resolved against the event DueReason received: issue.* and pull_request.* for the labeled item itself (title, number, html_url, body, and so on, whichever one fired), plus repository.*, label.* and sender.* for the event's other top-level fields. A field that is *only* one placeholder, like "{{issue.number}}", keeps that field's own type -- a number stays a number rather than becoming the text "42" -- while a placeholder embedded in a longer string is always turned into text. A path the event doesn't actually have resolves to null rather than breaking the delivery; what actually gates the request is still the target action's own payload schema, exactly as it would for a request filed any other way, so 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 label-triggered Zapier or n8n flow that posts to a chat channel 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.

What's not here yet

This closes the three planned inbound sources (GitHub, Linear, Jira); there is no installable GitHub App or Marketplace listing to add this to a repository -- every endpoint is configured by hand, per organization, in DueReason's own console, against a GitHub, Linear or Jira webhook you set up yourself the same way you would for any other integration.

Questions

Does removing a label also open a request?
No. Only the GitHub webhook action labeled matches -- adding the configured label to an issue or pull request. Unlabeling, commenting, closing, or any other issue/pull-request event is ignored, with no request opened and no error either.
What if GitHub retries a delivery because the first attempt timed out?
GitHub resends the same X-GitHub-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 whsec_... value from DueReason's outbound webhooks?
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 your GitHub repository's webhook settings, so DueReason can verify deliveries GitHub sends it.
Can I wire this up for Linear or Jira instead of GitHub?
Yes, both. Pick source Linear and configure a team key and target workflow state, or pick source Jira and configure a project key and target status -- either one opens the request the same way GitHub's label match does. Jira's endpoint is authenticated with a shared secret header (X-DueReason-Jira-Secret) rather than an HMAC signature, since Jira Cloud's own webhook registration has no HMAC-secret field.
Do I need to install a GitHub App or list this in the GitHub Marketplace?
No. Each endpoint is a webhook you add in your own repository's Settings > Webhooks, pointed at a URL DueReason generates for your organization. There is no GitHub App to install and no Marketplace listing involved.
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 GitHub label

Add an inbound GitHub endpoint in Settings > Inbound webhooks, point your repository's webhook at it, and label an issue to see the request appear.

Create your account

Sources

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.

Start with DueReason

Create a free account, try it live, or talk to us about your workflow.

Get product updates