Skip to content

DueReason API v1

API reference

The DueReason API lets your team, pipelines and AI agents ask a person for approval before they act, and keeps the reasons on record. List the actions your organization accepts, request approval with a payload and a reason, wait for the grant, verify it, then execute and report back. Each step is a ledgered event, and a signed, independently verifiable receipt closes the loop.

Base URL
https://www.duereason.com/api/v1
OpenAPI 3.1 document
/api/v1/openapi.json

Machine-readable description of every endpoint and webhook, for client generators and request validation.

Requests and responses are JSON (UTF-8). Timestamps are ISO 8601 in UTC. Request bodies are limited to 256 KB.

Start with DueReason

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

Get product updates

Integration flow

  1. List the actions your organization accepts approval requests for with GET /actions, each with the payload schema a request must satisfy.
  2. Ask for approval: POST /approvals with the action, an exact payload and your reason. The organization's workflows decide who must approve; a request matching no workflow is refused up front with no_workflow.
  3. Wait for the approval.approved or approval.rejected webhook, or poll GET /approvals/{id}?wait=N. Never act before the request is approved.
  4. Verify the grant POST /grants/verify returns before you rely on it, or check its signature yourself against the organization's JWKS.
  5. Carry out the approved action, then report what happened with POST /approvals/{id}/executions. A grant is single-use.
  6. Fetch the signed decision receipt with GET /approvals/{id}/receipt: a self-contained record you, an approver or an auditor can verify without a DueReason account.

Authentication

Every request carries an API key as a bearer token. Owners and admins create keys in the console under Settings, API keys, optionally with an expiry; the full key is shown once, DueReason stores only its SHA-256 hash.

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A missing, malformed, expired or revoked key gets 401. A valid key without the scope an endpoint needs gets 403 with the code insufficient_scope. Keys are never accepted in the query string.

Scopes

ScopeAllows
approval:requestAsk for approval, cancel your own pending requests, and report what happened once the grant is used.
approval:readRead approval requests, their answers and grants; verify grants.
action:readRead the actions you may ask approval for and their payload schemas.
action:manageCreate, update and delete actions and workflows (config as code). Not granted by default; never combinable with approval:request on the same key, since that key could then auto-approve its own requests. Writes are audited with the key as actor, and turning autoApprove on emails the organization's owners.
mandate:readRead mandates and their usage.
mandate:revokeRevoke a mandate your organization issued.
webhook:manageCreate and list webhook endpoints, and read their signing secret once, at creation.
Platform-work module (off by default)
ScopeAllows
decision:readRead decisions, their ledger events and the ledger head.
decision:requestCreate and withdraw decisions, relay review requests.
decision:enactConfirm that a decision has taken effect.
statement:issueIssue statements of reasons and receive worker portal links.
worker:readRead worker records.
worker:writeCreate and update worker records.
system:readRead the register of automated systems.
notice:readRead DSA notices (DSA add-on).
notice:writeRelay DSA notices received through your own interface (DSA add-on).

No scope can answer an approval request: only the people a workflow names can respond, in the console or from a notification.

Idempotency

Every POST requires an Idempotency-Key header: any string of 1 to 200 characters that you generate once per logical operation, such as a UUID. Retrying with the same key never repeats the effect.

  • Same key and the same request (method, path and body): you get the original status and body again, byte for byte, with the header Idempotent-Replayed: true.
  • Same key with a different request: 422 with the code idempotency_key_reused.
  • Same key while the first request is still running: 409 with the code idempotency_key_in_use. Retry after a short pause.

Only successful responses are remembered. A request that failed changed nothing, so retrying it with the same key runs it again, for example after a reviewer has approved the decision.

Keys are remembered for 24 hours. PUT is idempotent by definition and does not take the header.

Rate limits

Each API key may make up to 600 requests a minute, counted in a fixed one-minute window and enforced per key, not per organization or IP address. A key shared by several workers or agents draws from the same budget, and every response, successful or not, carries the three headers below.

HeaderMeaning
RateLimit-LimitThe limit for the current window: 600.
RateLimit-RemainingRequests left in the current window.
RateLimit-ResetSeconds until the window resets.

Exceeding the limit answers 429 with the problem code rate_limited and a Retry-After header giving the number of seconds to wait.

Example 429 response
{
  "type": "https://www.duereason.com/docs/api#error-rate_limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "This API key made more than 600 requests in a minute. Retry after 12 s.",
  "code": "rate_limited",
  "details": {
    "limit": 600,
    "retryAfterSeconds": 12
  }
}

RateLimit-Limit: 600 RateLimit-Remaining: 0 RateLimit-Reset: 12 Retry-After: 12

Back off for Retry-After seconds rather than a fixed delay. @duereason/sdk already retries 429s this way automatically; you only need to handle this yourself when you call the REST API directly.

CORS

Every /api/v1 operation allows cross-origin requests from any browser origin, the same policy already used for /api/v1/openapi.json. The API key is a bearer token you send explicitly in the Authorization header, never an ambient credential like a cookie, so there is no CSRF-style risk in that choice; it means a browser-based integration (an internal admin page, a Retool/Glide custom component) gets DueReason's real problem+json errors instead of an opaque network failure.

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS

Every response carries the headers below. A preflighted request (anything with a custom header, such as Authorization or Idempotency-Key) gets a 204 with the same headers from an OPTIONS request that never reaches authentication.

Errors

Errors are RFC 9457 problem documents with the media type application/problem+json. Branch on code, which is stable; detail is a human-readable explanation that is safe to log. Validation errors list each problem in details.issues with its location (path, query or body) and field path.

{
  "type": "https://www.duereason.com/docs/api#error-invalid",
  "title": "Invalid request",
  "status": 422,
  "detail": "The request body is invalid.",
  "code": "invalid",
  "details": {
    "issues": [
      {
        "in": "body",
        "path": "facts",
        "message": "Invalid input: expected string, received undefined"
      }
    ]
  }
}
CodeStatusMeaning
malformed_json400The body is not valid JSON.
idempotency_key_required400A POST without an Idempotency-Key header, or with one longer than 200 characters.
unauthorized401The API key is missing, malformed, expired or revoked.
payment_required402The organization's subscription has lapsed, so new approval requests and decisions are refused; details.billingUrl is where an owner or admin chooses a plan. Reads, cancelling, reporting executions and verifying grants keep working.
insufficient_scope403The key does not have the scope this endpoint needs; details.requiredScope names it.
forbidden403The action is not allowed for an API key at all.
not_found404No such resource in your organization. Another organization's ids also give 404.
conflict409The decision is not in a state that allows this, for example enacting a decision that is still pending_human, or the externalRef is taken.
not_pending409The approval request is not in a state that allows this: cancelling a request that is already decided, or reporting an execution for one that is not approved.
not_decided409The request has not been decided yet; a receipt exists once it is approved, rejected, expired or cancelled.
already_responded409This person has already answered the request (console only).
already_executed409An execution was already reported for this grant; a grant is single-use.
idempotency_key_in_use409A request with the same Idempotency-Key is still running.
precondition_failed412Something else must happen first, for example activating the cited system, or the person is a P2B business user to whom Art. 11 does not apply. Notice endpoints also answer 412 while the DSA add-on is off.
payload_too_large413The body is larger than 256 KB.
unsupported_media_type415The body is not sent as application/json.
invalid422The request failed validation; details.issues lists every problem.
no_workflow422No active workflow of the action applies to the request, so it cannot be approved. Nothing was created.
invalid_payload422The payload does not satisfy the action's payload schema; details.problems lists why.
idempotency_key_reused422The Idempotency-Key was already used for a different request.
rate_limited429More than 600 requests in a minute from this key. Wait for the number of seconds in Retry-After. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.
internal500Something failed on our side. Retrying with the same Idempotency-Key is safe.
grants_unavailable503The request is approved but its grant cannot be signed right now, a configuration problem on our side. Retry later.
scanner_unavailable503Files sent with a multipart POST /approvals could not be checked for malware (the scanner did not answer in time). Nothing was stored; retry in a few minutes.

Pagination

Lists return the newest items first in data, with nextCursor. Pass it as the cursor query parameter to get the next page; it is null on the last page. limit is 1 to 100, 50 by default.

Endpoints

Approvals

DueReason: ask people for approval before an agent or a system does something consequential, follow the request, and verify the signed grant before you act.

GET/api/v1/actions

List actions

The actions your organization accepts approval requests for, each with the payload schema a request must satisfy, alphabetical by key, one page at a time. Only active actions are listed by default; pass include=inactive to also see actions nobody can request against right now. Follow nextCursor (pass it back as cursor) until it is null.

Scope
action:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/actions?include=inactive" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/actions/{key}

Get an action

One action by its key, active or not, with its payload schema and grant validity.

Scope
action:read
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/actions/payment" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/actions

Create an action

Define a new kind of thing your organization accepts approval requests for: its key (immutable, what agents send as action), name, payload schema and grant validity. Requires action:manage, a scope not granted by default and never combinable with approval:request on the same key, since that key could then approve its own requests.

Scope
action:manage
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/actions" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "payment",
  "name": "Payment",
  "description": "Pay a supplier invoice.",
  "payloadSchema": {
    "type": "object",
    "properties": {
      "amount": {
        "type": "number",
        "minimum": 0
      },
      "currency": {
        "type": "string",
        "format": "currency"
      },
      "payee": {
        "type": "string"
      }
    },
    "required": [
      "amount",
      "currency",
      "payee"
    ]
  }
}'
PATCH/api/v1/actions/{key}

Update an action

Change an action's name, description, payload schema, grantTtlSeconds or whether it is active. The key is immutable. Narrowing the payload schema can make requests other integrations already send start failing validation.

Scope
action:manage
Success
200
Example
curl -X PATCH "https://www.duereason.com/api/v1/actions/payment" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
GET/api/v1/workflows

List workflows

The approval rules your organization has configured: when each applies (its conditions), who must approve (its steps), and whether it auto-approves instead of asking a human. Newest first, one page at a time; follow nextCursor (pass it back as cursor) until it is null. A condition's value keeps its original JSON type (a boolean stays true/false, never the string "true"), so you can tell a true/false check from a text comparison. Filter by action to see only the workflows that govern it.

Scope
action:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/workflows?action=payment" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/workflows/{id}

Get a workflow

One workflow with its conditions, steps and current version.

Scope
action:read
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/workflows/wfl_0192a703e5f76a8b9c0d1e2f3a4b5c6d" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/workflows

Create a workflow

Add an approval rule for an action: its conditions, steps and whether it auto-approves. Requires action:manage. A condition's value must match the type its payload property declares (a boolean property needs true/false, never the string "yes"). Creating a workflow with autoApprove true emails the organization's owners and posts to any Slack/Teams channel subscribed to security.auto_approve_enabled, so a self-approving setup is never silent.

Scope
action:manage
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/workflows" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "actionKey": "payment",
  "name": "Payments over 1000",
  "priority": 10,
  "definition": {
    "conditions": [
      {
        "field": "payload.amount",
        "op": "gte",
        "value": 1000
      }
    ],
    "autoApprove": false,
    "steps": [
      {
        "name": "Finance",
        "groups": [
          "grp_finance"
        ],
        "users": [],
        "required": 1,
        "evidence": "none"
      }
    ]
  }
}'
PATCH/api/v1/workflows/{id}

Update a workflow

Change a workflow's name, description, priority, whether it is active, or replace its whole definition (conditions, autoApprove and steps together, like the console's editor — there is no way to patch a single condition). Requires action:manage. Turning autoApprove on notifies the organization's owners the same way creating one does.

Scope
action:manage
Success
200
Example
curl -X PATCH "https://www.duereason.com/api/v1/workflows/wfl_0192a703e5f76a8b9c0d1e2f3a4b5c6d" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
DELETE/api/v1/workflows/{id}

Delete a workflow

Remove an approval rule. Requests already made keep the snapshot of the workflow they matched. Requires action:manage.

Scope
action:manage
Success
200
Errors
not_found
Example
curl -X DELETE "https://www.duereason.com/api/v1/workflows/wfl_0192a703e5f76a8b9c0d1e2f3a4b5c6d" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/approvals

Request approval

Asks for approval of one action with an exact payload and a reason. The organization's workflows decide who must approve. When none applies the request is refused with no_workflow (fail closed), and a payload the action's schema rejects is refused with invalid_payload. Approvers are emailed as each step opens. Do not carry out the action until the request is approved and you hold its grant.

Scope
approval:request
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/approvals" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "payment",
  "title": "Pay invoice INV-2026-118",
  "reason": "Due to the reason of: the supplier'\''s invoice is due on 10 October and matches PO-77.",
  "payload": {
    "amount": 1200,
    "currency": "EUR",
    "payee": "ACME sp. z o.o.",
    "invoice": "INV-2026-118"
  },
  "agent": {
    "name": "ap-agent",
    "model": "claude",
    "runId": "run_8812"
  },
  "context": [
    {
      "label": "Invoice",
      "url": "https://erp.example.com/invoices/INV-2026-118"
    }
  ],
  "expiresInSeconds": 86400
}'

Send multipart/form-data instead: the same request JSON as a string part, plus one or more files. Same validation, size limits and malware scan as the console.

Example with attachments
curl -X POST "https://www.duereason.com/api/v1/approvals" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request=<request.json;type=application/json' \
  -F files=@sbom.json
GET/api/v1/approvals

List approval requests

Newest first, filtered by status and action. An approved request includes its grant.

Scope
approval:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/approvals?status=pending&action=payment&q=invoice%20118&limit=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/approvals/{id}

Get an approval request

One request with its steps, answers, evidence and, once approved, its grant. With wait=N (at most 20) the call holds until the request changes or N seconds pass, then answers. Webhooks (approval.approved, approval.rejected and the rest), or the SDK and MCP wait loops built on this call, are the primary way to learn the outcome; wait is a convenience.

Scope
approval:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c?wait=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/approvals/{id}/cancel

Cancel an approval request

Withdraws a pending request. Through the API only the key that created it may cancel it; a request that is already decided answers not_pending.

Scope
approval:request
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/cancel" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
GET/api/v1/approvals/{id}/precedents

Get an approval request's precedents

The most similar decided requests of the same action in the last year, newest-scored first, each with its outcome, who decided, their written reason (truncated to 300 characters) and the evidence filenames they attached. Also a summary of every decided request in the window: counts by outcome and the most recent rejection's reason. Deterministic and local: no AI call, just similarity on the action's payload schema plus title and reason.

Scope
approval:read
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/precedents?limit=5" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/approvals/{id}/comments

List an approval request's comments

The discussion thread on a request, oldest first within the page: a clarifying question, extra context, or a reply, each with who wrote it and when. Keyset-paginated, newest page first; pass nextCursor back as cursor for the page of comments older than what you already fetched.

Scope
approval:read
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/comments?limit=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/approvals/{id}/comments

Post an approval request comment

Adds to the discussion thread on a request, attributed to the calling API key (not a named person). Requires approval:request, the same scope that creates and cancels requests. Posting never changes the request's status. Rate-limited separately from the console's own comment budget. Never parsed for @[Name](memberId)-shaped mentions, even if the body happens to contain that pattern — only the console composer's own token means a real mention.

Scope
approval:request
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/comments" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Confirmed against PO-77; the vendor matches our records."
}'
POST/api/v1/precedents/check

Check precedents before filing a request

The same similar-past-decisions search as GET /approvals/{id}/precedents, one step earlier: keyed on an action and payload you intend to send, not an existing request id, so an agent calling the API directly can see how similar requests have gone before it decides what to ask for. Optionally takes the title and reason drafted so far to sharpen the text-similarity signal. Informational only: it never blocks or changes a later POST /approvals.

Scope
approval:read
Success
200
Errors
not_found

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/precedents/check" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "actionKey": "payment",
  "payload": {
    "amount": 1200,
    "currency": "EUR",
    "payee": "Hosting Ltd"
  }
}'
POST/api/v1/approvals/{id}/executions

Report an execution

Tells DueReason the grant was used, and how it went. The grant must belong to this request and must not have expired. A grant is single-use: a second report answers already_executed.

Scope
approval:request
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/executions" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "grant": "eyJhbGciOiJFZERTQSIsImtpZCI6Imdza18uLi4iLCJ0eXAiOiJkdWVyZWFzb24tZ3JhbnQrand0In0.eyJzdWIiOiJhcHJfLi4uIn0.c2lnbmF0dXJl",
  "outcome": "succeeded",
  "detail": "Bank transfer TX-55120"
}'

Send multipart/form-data instead: the same request JSON as a string part, plus one or more files. Same validation, size limits and malware scan as the console.

Example with attachments
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/executions" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request=<request.json;type=application/json' \
  -F files=@sbom.json
POST/api/v1/grants/verify

Verify a grant

Checks a grant's signature, organization and expiry, and that it was issued for exactly this payload. For executors without a JWS library; others verify offline against the organization's keys at /.well-known/duereason/ORG-SLUG/jwks.json. An invalid grant is still a 200, with valid false and a reason.

Scope
approval:read
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/grants/verify" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "grant": "eyJhbGciOiJFZERTQSIsImtpZCI6Imdza18uLi4iLCJ0eXAiOiJkdWVyZWFzb24tZ3JhbnQrand0In0.eyJzdWIiOiJhcHJfLi4uIn0.c2lnbmF0dXJl",
  "payload": {
    "amount": 1200,
    "currency": "EUR",
    "payee": "ACME sp. z o.o.",
    "invoice": "INV-2026-118"
  }
}'
GET/api/v1/approvals/{id}/receipt

Get a decision receipt

A self-contained, signed record of this decided request: the payload and its hash, the requester, every step's responses and evidence hashes, the grant if one was issued, and the request's own ledger events. 409 not_decided while the request is still pending. See docs/duereason/receipts.md for the format and how to verify one — offline, with @duereason/sdk's verifyReceipt(), or at https://duereason.com/verify, none of which need a DueReason account.

Scope
approval:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/receipt" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/receipts

Export decision receipts in bulk

Every decided request's receipt whose decidedAt falls in [from, to), oldest first, cursor-paginated like the other list endpoints. Pending requests are never included. Each receipt is identical to what GET /approvals/{id}/receipt returns for that request. The range cannot exceed 92 days; page through a wider period with several calls. Built for an organization that wants its own periodic audit trail (e.g. every receipt from a quarter) without fetching each approval by hand.

Scope
approval:read
Success
200
Errors
forbidden
Example
curl -X GET "https://www.duereason.com/api/v1/receipts?from=2026-07-01T00:00:00Z&to=2026-10-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Mandates

Standing, bounded, revocable authority: delegate a slice of an approval decision in advance so matching requests are approved automatically, metered and ledgered. Off by default; an org owner/admin turns it on in Settings. Issued by a person in the console (Settings > Mandates) only; the API reads, checks and revokes mandates.

GET/api/v1/mandates

List mandates

Standing authority your organization has delegated, newest first. Filter by actionId or activeOnly (not revoked and within its validity window).

Scope
mandate:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/mandates" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/mandates/{id}

Get a mandate

One mandate with its constraints, limits and current-period usage.

Scope
mandate:read
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/mandates/mdt_0192a6f3d4e65f8a9b0c1d2e3f4a5b6c" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/mandates/{id}/revoke

Revoke a mandate

Immediate: no request after this is covered by the mandate again. Only org owner/admin or the mandate's issuer may revoke it.

Scope
mandate:revoke
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/mandates/mdt_0192a6f3d4e65f8a9b0c1d2e3f4a5b6c/revoke" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "SaaS seat cancelled."
}'
POST/api/v1/mandates/check

Check mandate coverage

See in advance whether a request like this would be auto-approved under a mandate, and how much budget is left on it, without creating a request or consuming anything. Runs the exact same matching logic POST /approvals uses, so the verdict here and a real submission's can never disagree. Fails closed: mandates disabled, an unknown action, or an internal error all answer covered: false with a reason in a 200, never a false positive.

Scope
mandate:read
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/mandates/check" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "actionKey": "payment",
  "payload": {
    "amount": 120,
    "currency": "EUR",
    "payee": "Hosting Ltd"
  },
  "agent": {
    "name": "ap-agent"
  }
}'

Webhooks

Register, update, disable, remove and rotate the secret of the endpoints DueReason delivers approval.* and decision.* events to; inspect and redeliver past deliveries, or send a test event. See Webhooks below for the payload, headers and verifying signatures.

GET/api/v1/webhooks

List webhook endpoints

Your organization's webhook endpoints, newest first. Never includes the signing secret; it is shown only once, in the create response (or the console, on rotation).

Scope
webhook:manage
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/webhooks" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/webhooks/{id}

Get a webhook endpoint

One webhook endpoint by id: its url, subscribed events, active flag and signing-secret rotation state. Never includes the signing secret itself; it is shown only once, in the create response (or the console, on rotation).

Scope
webhook:manage
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/webhooks

Create a webhook endpoint

Registers an HTTPS endpoint and the events it receives. The signing secret (whsec_...) is in this response only; store it immediately, you cannot read it again.

Scope
webhook:manage
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/webhooks" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/duereason",
  "events": [
    "approval.approved",
    "approval.rejected"
  ]
}'
PATCH/api/v1/webhooks/{id}

Update a webhook endpoint

Toggles active or replaces the subscribed event list (events, when given, replaces it whole; omit either field to leave it unchanged). A disabled endpoint receives no new deliveries; already-queued ones keep waiting until you re-enable it or redeliver them.

Scope
webhook:manage
Success
200
Example
curl -X PATCH "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
DELETE/api/v1/webhooks/{id}

Delete a webhook endpoint

Removes the endpoint and its delivery history. There is no undo; register a new endpoint to resume receiving events.

Scope
webhook:manage
Success
200
Errors
not_found
Example
curl -X DELETE "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/webhooks/{id}/rotate-secret

Rotate a webhook endpoint's signing secret

Issues a new signing secret immediately. Deliveries queued before this call were already signed with the old secret; everything sent after uses the new one right away. The secret this rotation replaced is in this response and, for 24h, readable once more in the console while you roll your receiver's verification over; after that it is gone for good.

Scope
webhook:manage
Success
200
Errors
not_found

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e/rotate-secret" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
GET/api/v1/webhooks/{id}/deliveries

List a webhook endpoint's deliveries

Delivery attempts for one endpoint, newest first, including pending and failed ones. Optionally filter by status or eventType. limit defaults to 50 and is capped at 200.

Scope
webhook:manage
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e/deliveries?limit=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/webhooks/{id}/test

Send a test event

Queues a synthetic test delivery through the same pipeline as a real event (signing, SSRF checks, retries), so you can confirm the URL, secret and signature verification before a real event fires. 412 precondition_failed on a disabled endpoint.

Scope
webhook:manage
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e/test" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/api/v1/webhooks/deliveries/{deliveryId}/redeliver

Redeliver a webhook delivery

Queues the delivery again with a fresh retry budget, keeping its id and payload so your receiver can deduplicate on the DueReason-Delivery header. 412 precondition_failed while the endpoint is disabled.

Scope
webhook:manage
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/webhooks/deliveries/dlv_0192a7210817c8a9b0c1d2e3f4a5b6c7/redeliver" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Platform-work module (off by default)

These endpoints answer 412 precondition_failed until an organization owner turns the platform-work module on in Settings.

Decisions

Record decisions and follow them through the human gate: enact, withdraw, explain in writing and relay review requests.

POST/api/v1/decisions

Create a decision

Records a decision about a person in the ledger. Restrict, suspend and terminate start as pending_human and wait for a trained reviewer (Art. 10(5)); every other type is recorded immediately. An unknown workerRef is registered on the fly when workerCountry is given. Automated decisions must cite an active system by systemKey.

Scope
decision:request
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/decisions" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "workerRef": "courier-4821",
  "workerCountry": "PL",
  "systemKey": "fraud-score",
  "type": "suspend",
  "automatedDetection": true,
  "automatedDecision": false,
  "summary": "Account suspended for 7 days in all delivery zones.",
  "facts": "Five deliveries on 28 September were confirmed 3 km or more from the drop-off point, according to the GPS trace.",
  "contractualGround": "Terms of service, section 8.2 (accurate delivery confirmation).",
  "durationDays": 7,
  "externalRef": "case-2026-0931"
}'
GET/api/v1/decisions

List decisions

Decisions in your organization, newest first, optionally filtered by status or by person.

Scope
decision:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/decisions?status=pending_human&limit=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/decisions/{id}

Get a decision

One decision with its statement of reasons, if issued, and its open review request, if any. Keys with the statement:issue scope also receive the worker portal link.

Scope
decision:read
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/decisions/{id}/enact

Enact a decision

Confirms that you have acted on an approved or recorded decision. A decision still pending_human returns 409: enact only after the decision.approved webhook.

Scope
decision:enact
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/enact" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/api/v1/decisions/{id}/withdraw

Withdraw a decision

Withdraws a decision that is pending_human or approved and has not been enacted. The reason is recorded in the ledger.

Scope
decision:request
Success
200

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/withdraw" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Raised twice by the fraud pipeline; case-2026-0930 stands."
}'
POST/api/v1/decisions/{id}/statement

Issue the statement of reasons

Freezes the written statement of reasons (Art. 11(1); DSA Art. 17) for a decision in effect and returns a signed portal link for the person. If the worker has a contact email, DueReason also emails the link. Fails with 422 when the decision lacks the facts, a ground or a contact person.

Scope
statement:issue
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/statement" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "locale": "pl"
}'
POST/api/v1/decisions/{id}/review-requests

Relay a review request

Records that the person asked for a review through your own interface (Art. 11(2)). The two-week deadline starts now; one review may be open per decision.

Scope
decision:request
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/review-requests" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "comment": "The app froze and confirmed the wrong stop."
}'

Workers

Pseudonymous records of the people decisions are about.

PUT/api/v1/workers/{externalRef}

Create or update a worker

Creates the person under your pseudonymous reference, or updates the fields you send. Repeating the same request leaves the record unchanged. Erased workers return 409.

Scope
worker:write
Success
200
Errors
conflict
Example
curl -X PUT "https://www.duereason.com/api/v1/workers/courier-4821" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "country": "PL",
  "status": "self_employed",
  "activity": "regular",
  "locale": "pl",
  "contactEmail": "courier-4821@example.com"
}'
GET/api/v1/workers/{externalRef}

Get a worker

The worker record for your pseudonymous reference.

Scope
worker:read
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/workers/courier-4821" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Systems

The register of automated monitoring and decision-making systems (Art. 9).

GET/api/v1/systems

List systems

Active and draft entries of the automated-systems register with their current version. Only active systems may be cited by a decision.

Scope
system:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/systems" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Ledger

The hash-chained record of everything that happened to each decision.

GET/api/v1/decisions/{id}/events

List a decision's ledger events

Every event recorded for the decision, in chain order, with the hashes that link it to its predecessor.

Scope
decision:read
Success
200
Errors
not_found
Example
curl -X GET "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/events" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/ledger/head

Get the ledger head

The latest position and hash of your organization's platform-work decision chain and the result of its last full verification. Store the head in a system you control: a later head that does not extend it means the chain was rewritten.

Scope
decision:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/ledger/head" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/ledger/approvals/head

Get the approval ledger head

The latest position and hash of your organization's approval chain (every requested, answered, approved, executed and cancelled event) and the result of its last full verification. Store the head in a system you control: a later head that does not extend it means the chain was rewritten.

Scope
approval:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/ledger/approvals/head" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Notices

DSA add-on: notices of illegal content under Art. 16 of Regulation (EU) 2022/2065. While the add-on is off, these endpoints answer 412 with the code precondition_failed.

POST/api/v1/notices

Relay a notice

Records a notice of allegedly illegal content that a person sent through your own interface (Art. 16(1)). The notice must carry what Art. 16(2) requires: the location of the content, a substantiated explanation, the notifier's name and email (unless csamExemption is true for child sexual abuse material, with the category STATEMENT_CATEGORY_PROTECTION_OF_MINORS) and the good-faith statement. A notice that falls short is a 422 whose details.problems names each gap. When an email address is given, DueReason emails the confirmation of receipt (Art. 16(4)) in the notice's language, and later the decision with the redress options (Art. 16(5)). Notices are decided by people in the console.

Scope
notice:write
Success
201

Requires Idempotency-Key

Example
curl -X POST "https://www.duereason.com/api/v1/notices" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "contentUrls": [
    "https://example-platform.eu/listings/88213"
  ],
  "contentDescription": "Listing titled '\''Original designer handbag, new'\''.",
  "explanation": "The handbag is a counterfeit of a registered EU trade mark: the logo and serial number do not match the manufacturer'\''s.",
  "category": "STATEMENT_CATEGORY_INTELLECTUAL_PROPERTY_INFRINGEMENTS",
  "notifierName": "Anna Kowalska",
  "notifierEmail": "anna.kowalska@example.com",
  "goodFaith": true,
  "locale": "pl"
}'
GET/api/v1/notices/{id}

Get a notice

One notice with its status, the decision once taken, the ledger decision about the affected person if one is linked (its statement of reasons is the Art. 17 statement), and when the confirmation and the decision were emailed to the notifier.

Scope
notice:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/notices/ntc_0192a6d2b7c84e1f9a3b5c7d9e1f3a5b" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Webhooks

Owners and admins add endpoints under Settings, Webhooks and choose the events they receive, or * for all of them. Each event is POSTed as JSON to your HTTPS endpoint. The signing secret (whsec_...) is shown once when the endpoint is created or its secret is rotated.

An endpoint subscribed to an explicit list of events never automatically starts receiving an event type added to the product later; its list has to be updated to add the new type. Choose * instead to subscribe to every current and future event type without updating the endpoint again.

The body has id (the ledger event id), type, createdAt and data. For approval.* events, data always carries requestId and seq; for decision.* events (platform-work module), data carries decisionId and seq instead; plus the fields of that event.

approval.approved
{
  "id": "ape_0192a701b2c3d4e5f6a7b8c9d0e1f2a3",
  "type": "approval.approved",
  "createdAt": "2026-10-02T09:41:12.204Z",
  "data": {
    "requestId": "apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c",
    "seq": 3,
    "grantId": "grt_0192a6f8a1b23c4d5e6f7a8b9c0d1e2f",
    "approvers": [
      {
        "id": "usr_0192a6d2b3c4d5e6f7a8b9c0d1e2f3a4",
        "name": "Rita Nowak"
      }
    ],
    "auto": false,
    "mandateId": null
  }
}
approval.mandate.threshold_reached (org-level mandate event: no requestId/seq)
{
  "id": "dlv_0192a7b4c5d6e7f8a9b0c1d2e3f4a5b6",
  "type": "approval.mandate.threshold_reached",
  "createdAt": "2026-10-06T08:03:19.880Z",
  "data": {
    "mandateId": "mdt_0192a6c0b1c2d3e4f5a6b7c8d9e0f1a2",
    "actionKey": "refunds.issue",
    "thresholdPercent": 80,
    "crossed": [
      {
        "kind": "cumulative",
        "pct": 83.5
      }
    ]
  }
}
decision.review_reversed (platform-work module)
{
  "id": "evt_0192a7a1b2c3d4e5f6a7b8c9d0e1f2a4",
  "type": "decision.review_reversed",
  "createdAt": "2026-10-05T14:22:47.512Z",
  "data": {
    "decisionId": "dec_0192a76e1f2a3b4c5d6e7f8a9b0c1d2e",
    "seq": 6,
    "reviewId": "rev_0192a7901a2b3c4d5e6f7a8b9c0d1e2f",
    "resolution": "Lowered-ranking penalty did not account for the worker's active appeal window; reversed.",
    "onTime": true
  }
}

Headers

HeaderValue
DueReason-EventThe event type, e.g. decision.approved.
DueReason-DeliveryDelivery id. Retries and manual redeliveries reuse it: deduplicate on it.
DueReason-SignatureTwo comma-separated parts: t, the Unix time of signing, and v1, the hex HMAC-SHA256 of t, a dot and the raw body, keyed with your secret.
User-AgentDueReason-Webhooks/1

Events

* subscribes an endpoint to every current and future event type, approval.* and decision.* alike; it is never itself a delivered type. The console's "Send test event" sends the synthetic test event instead, with the same envelope shape as whichever real event it mimics -- type is never test for a real delivery, and test is never subscribable.

EventDescriptionPayload fields beyond approval.approved's
approval.requestedAn approval request was created.action, title, reason, payloadHash, agent, context, requester, workflow, expiresAt, attachments
approval.step_openedA step opened and its approvers were notified.step, name, required, evidence
approval.respondedAn approver answered; the data carries the verdict, the comment and the evidence hashes.responseId, step, verdict, comment, approver, evidence
approval.approvedThe request was approved. Fetch it for the grant and act only with a valid grant.Same shape as approval.approved above (requestId, seq, grantId, approvers, auto, mandateId).
approval.rejectedAn approver rejected the request. Do not carry out the action.step, approver, comment
approval.expiredNobody decided before the request expired. Do not carry out the action.expiresAt
approval.cancelledThe requester cancelled the request.by, reason, decisionWithdrawn
approval.executedThe executor reported using the grant. The payload includes the grant it presented, as a record of what authorized the execution.outcome, detail, grant, evidence
approval.mandate.usedThe request was approved automatically under a standing mandate instead of a live decision.consumes
approval.mandate.issuedA mandate was issued, granting standing authority to auto-approve matching requests.actionKey, subject, issuerId, reason
approval.mandate.revokedA mandate was revoked and no longer auto-approves any request.actionKey, revokedBy, reason
approval.mandate.threshold_reachedA mandate crossed its configured usage alert threshold.actionKey, thresholdPercent, crossed
approval.step_reminder_sentNobody had answered the open step; its approvers were notified again.step
approval.step_escalatedNobody had answered for longer still; the workflow's escalation group was also notified.step, groupId
Platform-work module (off by default)
EventDescriptionPayload fields beyond approval.approved's
decision.requestedA decision was created.decisionId, requestedAt, type, status, workerRef, systemKey, systemVersion, automatedDetection, automatedDecision, summary, facts, legalGround, contractualGround, durationDays, externalRef
decision.approvedA trained reviewer approved a gated decision. You may now act on it.decisionId, note, reviewer
decision.rejectedA trained reviewer rejected a gated decision. Do not act on it.decisionId, note, reviewer
decision.enactedThe decision was confirmed as having taken effect.decisionId
decision.withdrawnThe decision was withdrawn before it took effect.decisionId, reason
decision.statement_issuedThe statement of reasons was issued.decisionId, statementId, contactName, contactEmail, reviewAvailable
decision.review_requestedThe person asked for a review; the two-week clock started.decisionId, reviewId, channel, dueAt
decision.review_upheldThe review confirmed the decision.decisionId, reviewId, resolution, onTime
decision.review_reversedThe review reversed the decision. Undo the measure and record the remedy.decisionId, reviewId, resolution, onTime
decision.remediedThe decision was rectified or compensated after a reversal.decisionId, reviewId, remedy, note

Verifying signatures

Verify it with @duereason/sdk's verifyWebhookSignature instead of computing the HMAC-SHA256 yourself: pass your endpoint secret, the raw request body and the header, and it checks the signature in constant time and rejects timestamps more than five minutes old to stop replays.

Node.js
import { verifyWebhookSignature } from "@duereason/sdk";
import express from "express";

const app = express();

// Keep the raw bytes: a re-serialized object would not match the signature.
app.post("/webhooks/duereason", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  const header = req.get("DueReason-Signature") ?? "";
  if (!verifyWebhookSignature(process.env.DUEREASON_WEBHOOK_SECRET, body, header)) {
    return res.status(400).end();
  }
  const event = JSON.parse(body);
  // Retries reuse DueReason-Delivery: skip ids you have already handled.
  if (event.type === "approval.approved") {
    // Now, and only now, run the business logic this request gated.
  }
  res.status(204).end();
});
Next.js (App Router)
// app/api/webhooks/duereason/route.ts
import { verifyWebhookSignature } from "@duereason/sdk";

export async function POST(request: Request) {
  const body = await request.text(); // raw bytes -- do not call request.json() first
  const header = request.headers.get("DueReason-Signature") ?? "";
  if (!verifyWebhookSignature(process.env.DUEREASON_WEBHOOK_SECRET!, body, header)) {
    return new Response(null, { status: 400 });
  }
  const event = JSON.parse(body);
  // Retries reuse DueReason-Delivery: skip ids you have already handled.
  if (event.type === "approval.approved") {
    // Now, and only now, run the business logic this request gated.
  }
  return new Response(null, { status: 204 });
}

Not on Node? A tested Python port of verifyWebhookSignature -- same header parsing, tolerance window and constant-time compare, stdlib only -- ships in the SDK's source tree as duereason/sdk/examples/python/verify_webhook_signature.py, next to the Python grant-verification example.

Delivery and retries

Any 2xx response within 10 seconds counts as delivered. Anything else is retried up to 8 attempts in total, waiting 30 seconds after the first failure and doubling each time, at most 6 hours apart. Redirects are not followed. After the last attempt the delivery is marked failed; you can redeliver it from the console.

A non-2xx status is retried the same way as a timeout or connection error -- 4xx responses included, unlike many other webhook providers that give up after a 4xx. The only failure that stops retrying immediately, without working through the full schedule, is the endpoint's signing secret failing to decrypt; everything else, including a URL that now fails outbound validation, keeps retrying on the schedule above.

Handle the request asynchronously and return a 2xx within the 10-second timeout: a handler that blocks past it looks identical to a dead endpoint, triggers a retry, and can end up delivering the same event twice once the slow response finally arrives. DueReason-Delivery stays the same across every retry of one logical delivery, so dedupe on it regardless of how many attempts it took.

After 5 consecutive deliveries to an endpoint exhaust their retries, the organization's owners and admins get one email about it -- not one per attempt -- linking to Settings > Webhooks; a successful delivery resets the counter immediately.

Inbound: GitHub issues and pull requests

The webhooks above are DueReason telling your systems about an approval. The other direction also exists: a labeled GitHub issue or pull request can open a DueReason approval request automatically. Add an endpoint under Settings > Integrations > Inbound webhooks, then paste the webhook URL and your own secret into the repository's GitHub webhook settings (content type application/json). DueReason verifies GitHub's HMAC-SHA256 signature over the raw body before acting, and a retried delivery (same X-GitHub-Delivery id) never opens a second request.

Configure inbound endpoints in Settings > Integrations > Inbound webhooks.

Self-hosting

Prefer to run DueReason yourself? One Postgres database and one Docker image (web, worker and migrator) get a working instance up in three commands, no build step.

bash
curl -fsSL https://duereason.com/self-host/quickstart.sh -o quickstart.sh
chmod +x quickstart.sh && ./quickstart.sh
docker compose pull && docker compose up -d

Self-hosted deployments run under the Elastic License 2.0: you may run, read and modify the code, but not offer it to others as a hosted or managed service, or circumvent its license-key functionality.