Skip to content
Sign inRequest access

Outbound webhooks

A generic outbound webhook POSTs a signed JSON payload to your own endpoint whenever a subscribed event fires on a project: new feedback, an assignment, a mention, a status or priority change, a resolution, or a report linked to a tracker issue. It’s the delivery path for automation, a custom bridge, or any service uMarker doesn’t integrate with directly.

This page is the developer reference for the payload and its signature. To connect the webhook and route it to a project, see Channels & routing.

A webhook receives whichever of these events the route subscribes it to:

Event Fires when
new_feedback New feedback is submitted to the project, including items ingested through the REST API.
assigned A report is assigned to a member.
mentioned A member is @mentioned in a comment.
status_change A report’s status changes to anything other than resolved.
priority A report’s priority changes.
resolved A report’s status changes to resolved, or a pin on it is marked done.
issue_linked A report is linked to an external tracker issue.

For integration work, new_feedback and issue_linked are usually the two you want: they let an external system react to reports arriving and to reports being turned into tracker work.

uMarker sends an HTTP POST to your endpoint with a JSON body and these headers:

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-uMarker-Event-Id: 6f1b2c9e-4a7d-4a1e-9c33-0e7b0a2f51dd
X-uMarker-Signature: t=1751362500,v1=8f43a1c9d0…e7

X-uMarker-Event-Id is the same value as the body’s id. It’s in a header as well so a receiver can de-duplicate before parsing a body it might reject.

The body is a compact JSON object describing the event and the affected report:

Webhook payload
{
"id": "6f1b2c9e-4a7d-4a1e-9c33-0e7b0a2f51dd",
"event": "issue_linked",
"account_id": 3,
"project": { "id": 7, "name": "Checkout" },
"feedback": {
"id": 84,
"status": "in_progress",
"url": "https://app.umarker.com/s/8f2c…/feedback/84"
},
"from": null,
"to": null,
"timestamp": "2026-07-01T09:15:00+00:00"
}
Field Type Description
id string A UUID identifying this event, stable across every retry. De-duplicate on it.
event string The event type: one of the seven above, or test for a test send.
account_id integer The owning account’s ID.
project.id integer The project’s ID.
project.name string The project’s name.
feedback.id integer The affected report’s ID.
feedback.status string The report’s current status.
feedback.url string A dashboard link to open the report.
from string | null The previous status. Populated for status_change, and for a resolved event that came from a status change. null on every other event.
to string | null The new status, on those same two events. On a priority event it instead holds the new priority (none, low, medium, high, urgent). null on every other event.
timestamp string ISO 8601 time the event happened, not the time of the current retry.

For a status_change, from and to carry the transition:

status_change payload
{
"id": "b90d7a41-2f6c-4f0e-8d2a-1c5f9a3e77b2",
"event": "status_change",
"account_id": 3,
"project": { "id": 7, "name": "Checkout" },
"feedback": { "id": 84, "status": "resolved", "url": "https://app.umarker.com/s/8f2c…/feedback/84" },
"from": "in_progress",
"to": "resolved",
"timestamp": "2026-07-01T11:02:00+00:00"
}

A resolution carries the same pair, but arrives as a resolved event rather than a status_change — from: "in_progress", to: "resolved". The exception is a resolved event raised by marking a pin done, where both are null. On a priority event, to holds the new priority level and from is null.

The payload deliberately carries references, not content: an ID and a link, never the reporter’s words, another tenant’s data, or any credential. Fetch the full report through the REST API or open the dashboard link when you need more.

Every webhook request is signed so your receiver can prove it genuinely came from uMarker and wasn’t altered in flight. The signature is in the X-uMarker-Signature header:

X-uMarker-Signature: t=<unix-timestamp>,v1=<signature>
  • t: the Unix timestamp (seconds) at which the request was signed.
  • v1: the signature, an HMAC-SHA256 (hex) over the string <t>.<raw-body>, keyed with the channel’s signing secret.

In other words, uMarker computes:

signature = HMAC_SHA256( key = <channel secret>, message = "<t>.<raw request body>" )

The signature covers the exact bytes of the request body. To verify, recompute the same HMAC and compare.

  1. Read the X-uMarker-Signature header and split it on , into t=… and v1=….

  2. Take the raw, unparsed request body: the exact bytes received. Do not re-serialize the parsed JSON; whitespace or key-order changes will break the match.

  3. Compute HMAC-SHA256 of the string `${t}.${rawBody}` using the channel’s signing secret as the key, and hex-encode it.

  4. Compare your value to v1 using a constant-time comparison. A match proves authenticity and integrity; a mismatch means you reject the request.

  5. Optionally, reject the request if t is far from your current clock (e.g. more than a few minutes) to limit replay.

verify.js
const crypto = require('crypto');
// `rawBody` MUST be the exact bytes received (e.g. express.raw()), not a re-stringified object.
function verifyUMarker(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(',').map((kv) => kv.split('='))
);
const { t, v1 } = parts;
if (!t || !v1) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
// Constant-time compare; guard against length mismatch.
const a = Buffer.from(v1, 'hex');
const b = Buffer.from(expected, 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}

The secret is a 40-character value minted when the webhook connection is created. It’s encrypted at rest and excluded from the channel’s default serialization, so it can’t ride along in an unrelated response.

It’s returned only to someone who may rotate it: holders of integrations.rotatechannel. Connecting a channel, repointing one and rotating its secret return it in their response to a holder of that permission, and the Integrations list shows it to nobody else — so a role that can connect or repoint a channel but not rotate its secret never reads it. Beyond that, only the two ends (uMarker and your receiver) hold it.

If it leaks, rotate it from the Integrations page. Rotation is a hard cutover: the moment you rotate, deliveries are signed with the new secret and the old one stops validating. Update your receiver with the new secret before the next event fires. See Channels: rotate the signing secret.

Never blocks

Every event delivery is queued, so it never blocks the action that triggered it. Each destination is delivered independently: one failing never affects another, or your email. Send test is the one exception — it runs inside your request so it can hand back the real result.

Bounded retries

A 10-second timeout, then up to three attempts with a 10s and 30s backoff, before the connection is flagged as failing. The next successful send clears the flag.

No redirects

Delivery refuses to follow redirects and resolves IPv4 only, so a public endpoint can’t 302 or slip an unvetted address past the guard at send time.

Public HTTPS only

Endpoints are validated at save time: https only, and the host must resolve to a public address. Private, loopback, and metadata addresses are rejected.

Return a 2xx status promptly to acknowledge a delivery. Anything else (including a 3xx redirect) counts as a failure and is retried; after the retry ceiling, the connection is marked failing in the dashboard until its next successful send.