Integrations
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.
- Enter the Payload URL, for example
https://ci.example.com/moru. - Tick the Events to send. All of them are ticked to start with.
- 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
pingevent, 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-Type | application/json |
User-Agent | Moru-Webhooks/ and the node’s version |
X-Moru-Event | The event, such as change.revised |
X-Moru-Delivery | A UUID, the same on every retry of one delivery |
X-Moru-Signature-256 | sha256= 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#
| Event | When | Fields |
|---|---|---|
ping | You choose Ping | hook, zen |
change.created | A change is submitted for the first time | change, revision |
change.revised | Every revision, the first one included, and the revision that applying suggestions makes. This is the one to run CI on. | change, revision |
change.approved | A change is approved, with Approve or by an approving review | change |
change.merged | A change is merged into its target | change, merged_commit |
change.closed | A change is closed | change |
change.base | An open change starts or stops conflicting with its target branch | change, base |
request.created | A request is opened | request |
request.updated | A request changes: edited, accepted, declined, planned, closed or reopened; an attempt starts or ends; a change is linked | request, what |
tracker.updated | A label or milestone is added, changed or deleted | labels, milestones |
comment.created | A comment or a new thread, on a change, a request or a commit, posted on its own | subject, comment |
review.submitted | A review is submitted, by a person or a reviewer agent | subject, review |
bakeoff.recommended | A Bake-off’s reviewers have ranked its candidates | bakeoff, request |
push | A branch or tag moves: pushes, and merges, which move the target branch | ref, before, after |
ci.run.queued | A CI run is queued for a revision, a push or a manual start | run |
ci.run.started | A CI run starts, once: its first job leaves the queue. A run whose jobs are all skipped never starts | run |
ci.run.finished | A CI run ends: succeeded, failed, cancelled, or refused when its workflow has errors | run |
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_atis when this attempt was sent, in milliseconds since 1970, so a receiver can refuse old deliveries.urlfields are there when the node knows its public URL (--public-url).actoris the DID of whoever did it, when that’s a person or an agent. Merges are done by the node and have none.versiongoes 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.kindischange,requestorcommit;idis the change ID, the request ID or the commit ID.anchorisnullfor a comment that isn’t on lines of code. Hidden comments aren’t sent.review.outcomeiscomment,approveorrequest_changes.review.bodyis the summary, empty when there is none.review.revisionis the change revision reviewed.review.commentslists the comments the review added: new threads (new_threadtrue) and replies to existing threads.- In
commentand in each ofreview.comments, a new thread on lines that carries a suggested change hassuggestion.replacement, the full text that replaces linesstart_linetoend_line(empty to delete them); otherwisesuggestionisnull. bakeoff.winneris the change ID of the recommended candidate,nullif there is none.request.statusincludestriagefor a request filed by someone without write access, andrequest.triagestaystruefor it after it’s accepted.request.declined_reasonisduplicate,wont_do,not_reproducible,spamorotherwhile a decline stands.labelsandmilestoneare IDs;tracker.updatednames them.request.updatedhaswhatwhen it can say:edited,accepted,declined,planned,closedorreopened.merged_commitis the commit the change became on the target branch.- In a
push,refis the full ref name (refs/heads/main), andbeforeandafterare commit IDs,nullfor a branch that was just created or deleted. - A
pingalso 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 /webhooks | The hooks (without secrets), the events there are, and whether internal addresses are allowed |
POST /webhooks | Add 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}/secret | A new secret, in the answer |
POST /webhooks/{id}/ping | Send a ping |
GET /webhooks/{id}/deliveries | The last 50 deliveries, newest first |
POST /webhooks/{id}/deliveries/{delivery}/redeliver | Send 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.