Docs
Docs menu

Webhooks

Have Moru call a URL when something happens in a repository, what it sends, how to check the signature, and how deliveries are retried.

A repository’s admins can have Moru call a URL when something happens in it: a change is revised, a comment is posted, a branch is pushed. Use webhooks to start CI, post to chat, or keep another system in step.

Add a webhook#

Open the repository’s Settings tab and scroll to Webhooks. You need to be an admin of the repository.

  1. Enter the Payload URL, for example https://ci.example.com/moru.
  2. Tick the Events to send. All of them are ticked to start with.
  3. Choose Add webhook.

Moru shows the hook’s secret once. Copy it into your receiver: it uses the secret to check that each delivery came from Moru. If you lose it, New secret makes another, and deliveries are signed with the new one straight away.

Each hook in the list has these buttons:

  • Ping sends a ping event, to test the receiver.
  • Recent deliveries shows the last 50 deliveries: whether each was delivered, what was sent and what came back. Send again sends one again.
  • Edit changes the URL and the events.
  • Turn off and Turn on pause and resume a hook.
  • Delete removes the hook and its deliveries.

A repository can have up to 20 webhooks.

Deliveries#

Each delivery is an HTTP POST with a JSON body and these headers:

Header
Content-Typeapplication/json
User-AgentMoru-Webhooks/ and the node’s version
X-Moru-EventThe event, such as change.revised
X-Moru-DeliveryA UUID, the same on every retry of one delivery
X-Moru-Signature-256sha256= and the hex HMAC-SHA256 of the body, keyed with the hook’s secret

Any 2xx answer counts as delivered. Anything else, or no answer within 10 seconds, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then given up. Redirects aren’t followed.

A hook whose deliveries fail 50 times in a row turns itself off and shows Turned off with the reason. Turn it on again once the receiver works; that starts the count over.

Send again (or the API’s redeliver) sends the same payload as a new delivery, with a new delivery ID and a new sent_at.

Events#

EventWhenFields
pingYou choose Pinghook, zen
change.createdA change is submitted for the first timechange, revision
change.revisedEvery revision, the first one included, and the revision that applying suggestions makes. This is the one to run CI on.change, revision
change.approvedA change is approved, with Approve or by an approving reviewchange
change.mergedA change is merged into its targetchange, merged_commit
change.closedA change is closedchange
change.baseAn open change starts or stops conflicting with its target branchchange, base
request.createdA request is openedrequest
request.updatedA request changes: edited, accepted, declined, planned, closed or reopened; an attempt starts or ends; a change is linkedrequest, what
tracker.updatedA label or milestone is added, changed or deletedlabels, milestones
comment.createdA comment or a new thread, on a change, a request or a commit, posted on its ownsubject, comment
review.submittedA review is submitted, by a person or a reviewer agentsubject, review
bakeoff.recommendedA Bake-off’s reviewers have ranked its candidatesbakeoff, request
pushA branch or tag moves: pushes, and merges, which move the target branchref, before, after
ci.run.queuedA CI run is queued for a revision, a push or a manual startrun
ci.run.startedA CI run starts, once: its first job leaves the queue. A run whose jobs are all skipped never startsrun
ci.run.finishedA CI run ends: succeeded, failed, cancelled, or refused when its workflow has errorsrun

The comments, replies and suggestions in a review go out with its review.submitted, not as separate comment.created events. A review with the outcome approve also sends change.approved. Applying suggestions sends change.revised for the new revision, and a push when the change’s tracked branch moves with it.

change.base goes out when an open change’s latest revision stops applying to its target, and again when it applies once more: after a rebase, or because the target moved again. Being behind the target doesn’t send it. Nor does a change’s first check: a change that already conflicts when it’s first checked (for example after an upgrade, or one that conflicted when it was submitted) sends no change.base, though it does send one when it stops conflicting. A conflicting change that is merged or closed gets change.merged or change.closed, with no change.base after it. Its base has revision, state (conflicts; or, when it stops, current, applies, or unknown if the check couldn’t run), onto (the target commit it was checked against) and paths (the conflicting files, empty unless it conflicts).

A hook can also ask for a family of events: ci.* is every ci. event, including ones a later version adds. A run has id, workflow, workflow_name, trigger, ref, commit, change_id and revision (for a change’s run), state, delegated_by and url (the run’s page). A refused run’s ci.run.finished also has findings: how many problems its workflow has (read them on the run’s page).

Job logs and other internal events are never sent.

Payloads#

Every body has these fields:

{
	"version": 1,
	"event": "change.revised",
	"delivery": "5f0c3c1e-4d1b-4a8e-9a43-2b0e1c9d7f10",
	"sent_at": 1794239507594,
	"repo": { "name": "acme/timetable", "url": "https://moru.example.com/r/acme/timetable" },
	"actor": "did:plc:…"
}
  • sent_at is when this attempt was sent, in milliseconds since 1970, so a receiver can refuse old deliveries.
  • url fields are there when the node knows its public URL (--public-url).
  • actor is the DID of whoever did it, when that’s a person or an agent. Merges are done by the node and have none.
  • version goes up if a field changes meaning or goes away. New fields can appear at any time, so ignore the ones you don’t know.

The event’s own fields come next to these. The objects look like this:

"change": {
  "id": "uqlqvoqtnysywoyryqsmwlovzqyrxvnl",
  "title": "Add a function",
  "status": "open",
  "target": "refs/heads/main",
  "author": "did:key:…",
  "revisions": 2,
  "url": "https://moru.example.com/r/acme/timetable/changes/uqlqvoqtnysywoyryqsmwlovzqyrxvnl"
},
"revision": { "number": 2, "commit": "da8afbe0c1…", "base": "5a5f9313e9…" },
"base": { "revision": 2, "state": "conflicts", "onto": "e4c01b7a2f…", "paths": ["src/lib.rs"] },
"request": {
  "id": "…",
  "title": "…",
  "status": "in_progress",
  "author": "did:…",
  "triage": false,
  "declined_reason": null,
  "kind": "bug",
  "priority": "high",
  "milestone": "…",
  "labels": ["…"],
  "url": "…"
},
"labels": [{ "id": "…", "name": "bug", "colour": "red", "description": "…" }],
"milestones": [{ "id": "…", "title": "2026.12", "due": "2026-12-15", "closed": false }],
"comment": {
  "id": "…",
  "thread_id": "…",
  "body": "Markdown, as written",
  "author": "did:…",
  "new_thread": true,
  "anchor": { "path": "src/lib.rs", "start_line": 4, "end_line": 6, "revision": 2 },
  "suggestion": null,
  "url": "…#thread-…"
},
"review": {
  "id": "…",
  "outcome": "request_changes",
  "body": "Markdown summary, as written",
  "author": "did:…",
  "revision": 2,
  "comments": [
    {
      "id": "…",
      "thread_id": "…",
      "body": "This can't be empty.",
      "new_thread": true,
      "anchor": { "path": "src/lib.rs", "start_line": 4, "end_line": 4, "revision": 2 },
      "suggestion": { "replacement": "    assert!(!name.is_empty());\n" }
    }
  ],
  "url": "…#review-…"
},
"subject": { "kind": "change", "id": "…" },
"bakeoff": { "id": "…", "winner": "…" },
"hook": { "id": "…", "events": ["change.revised", "push"] }
  • subject.kind is change, request or commit; id is the change ID, the request ID or the commit ID.
  • anchor is null for a comment that isn’t on lines of code. Hidden comments aren’t sent.
  • review.outcome is comment, approve or request_changes. review.body is the summary, empty when there is none. review.revision is the change revision reviewed.
  • review.comments lists the comments the review added: new threads (new_thread true) and replies to existing threads.
  • In comment and in each of review.comments, a new thread on lines that carries a suggested change has suggestion.replacement, the full text that replaces lines start_line to end_line (empty to delete them); otherwise suggestion is null.
  • bakeoff.winner is the change ID of the recommended candidate, null if there is none.
  • request.status includes triage for a request filed by someone without write access, and request.triage stays true for it after it’s accepted. request.declined_reason is duplicate, wont_do, not_reproducible, spam or other while a decline stands. labels and milestone are IDs; tracker.updated names them.
  • request.updated has what when it can say: edited, accepted, declined, planned, closed or reopened.
  • merged_commit is the commit the change became on the target branch.
  • In a push, ref is the full ref name (refs/heads/main), and before and after are commit IDs, null for a branch that was just created or deleted.
  • A ping also has "zen": "Hello from Moru.".

Check the signature#

Compute the HMAC-SHA256 of the raw body with the secret, and compare it with the X-Moru-Signature-256 header in constant time, before you parse the JSON. In Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';

const secret = process.env.MORU_WEBHOOK_SECRET;

createServer((req, res) => {
	const chunks = [];
	req.on('data', (c) => chunks.push(c));
	req.on('end', () => {
		const body = Buffer.concat(chunks);
		const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
		const got = req.headers['x-moru-signature-256'] ?? '';
		const ok =
			got.length === expected.length && timingSafeEqual(Buffer.from(got), Buffer.from(expected));
		if (!ok) return res.writeHead(401).end();
		const event = JSON.parse(body);
		if (Date.now() - event.sent_at > 5 * 60_000) return res.writeHead(400).end('too old');
		console.log(event.event, event.repo.name);
		res.writeHead(204).end();
	});
}).listen(8080);

Answer quickly and do the work afterwards: a receiver that takes longer than 10 seconds counts as failed, and the delivery is retried.

Addresses#

By default a webhook can only call public addresses. Moru refuses URLs that resolve to localhost, private networks (10.0.0.0/8, 192.168.0.0/16 and the like), and link-local addresses such as cloud metadata services. It checks the address on every attempt and connects to the address it checked, so a name that later resolves somewhere else can’t get past the check.

A node whose integrations run inside its own network can allow internal addresses with moru-node serve --webhooks-allow-private (MORU_WEBHOOKS_ALLOW_PRIVATE=true). The Webhooks section then stops saying “Only public addresses”.

The API#

Every webhook action is also in the REST API, for repository admins, under /api/v0/repos/{owner}/{name}:

GET /webhooksThe hooks (without secrets), the events there are, and whether internal addresses are allowed
POST /webhooksAdd one: url, and optionally events (every event when left out) and active. The answer has its secret.
PATCH /webhooks/{id}Change url, events or active. Turning a hook on clears its run of failures.
DELETE /webhooks/{id}Delete a hook and its deliveries
POST /webhooks/{id}/secretA new secret, in the answer
POST /webhooks/{id}/pingSend a ping
GET /webhooks/{id}/deliveriesThe last 50 deliveries, newest first
POST /webhooks/{id}/deliveries/{delivery}/redeliverSend that payload again, as a new delivery

For example, to add a hook for revisions and pushes:

curl -X POST https://moru.example.com/api/v0/repos/acme/timetable/webhooks \
  -H "Authorization: Bearer $MORU_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://ci.example.com/moru", "events": ["change.revised", "push"]}'

Where hooks are kept#

Hooks are node configuration, kept in the node’s data directory (webhooks/<owner>/<name>.json), so backups include them. They aren’t part of the repository: a copy of the repository on another node has none, and doesn’t start calling your endpoints.

Command menu
Search for a page, repository, change or request, or run a command