Inbound webhooks
Let an external system POST a signed event to a per-webhook URL and have a Naumu agent act on it inside your space.
An inbound webhook - listed under Webhooks in the app - turns an event your own scripts, CI jobs or automation tools send into agent action inside one of your spaces. You give your sender a private URL to POST to, and it signs each request the Naumu way (see Sign each delivery). Services that sign webhooks their own way, such as GitHub or Stripe, can't post to the URL directly; relay their events through a small script that re-signs them. Each delivery runs an agent against the payload using instructions you wrote in advance.
This page is for developers wiring an external service into Naumu. For the mirror direction - Naumu driving your own agent runtime with signed outbound webhooks - see external agents.
Webhooks belong to a space, not to your account. Open the space's settings, go to Integrations, and select the Webhooks tab. Creating and managing webhooks is reserved for space admins.
Create a webhook
Select New webhook. Everything is filled in inside one dialog:
- Name it - type the name straight into the dialog's heading. It is what the row is called in the list and what Naumu quotes back to you when it shows the signing secret. It is purely cosmetic; leave it blank and the webhook reads as Untitled webhook.
- Set its Home - who the deliveries reach - with the same sharing controls a note or a routine uses:
- Private - just you.
- Everyone in [space] - every member of the space.
- Topics - file it into one or more topics, so deliveries land where that work already lives.
- Under What, write the instructions the agent follows when a delivery arrives, such as "When a GitHub issue arrives, summarise it and create a task node." The incoming payload is handed to the agent as data to examine, never as commands, so a hostile payload can't rewrite what the agent does.
- Under Filing, choose whether Auto-file to other topics is on. Off - the default for a new webhook - keeps every delivery where the webhook itself is filed. On lets the agent also file a delivery thread into other topics it finds relevant.
- Select Create.
A second dialog then shows the webhook's URL and signing secret, once. Copy both immediately - the signing secret is shown only this once and cannot be retrieved later.
Every delivery runs as the space's Naumu agent, so there is no routing choice to make.
Where a delivery lands
Each delivery opens a thread in the space, and that thread inherits the webhook's Home exactly - a delivery never reaches anyone who could not already see the webhook.
- Private - the thread is yours alone, in your personal home in the sidebar. It stays conversational: post a follow-up question there and @Naumu answers.
- Everyone in [space] - the thread is shared with the whole space and, with no topic picked, sits in misc. It stays conversational too.
- Topics - the thread goes to those topics' members instead, and @Naumu does not reply automatically -
@-mention it when you want it to weigh in.
Changing a webhook's Home applies to the next delivery; threads already delivered keep the audience they were created with.
Sign each delivery
Naumu only acts on deliveries it can verify came from you, so every POST must be signed with the webhook's signing secret. Send these headers alongside the JSON body:
| Header | Value |
|---|---|
X-Naumu-Webhook-Id | A unique id for this delivery |
X-Naumu-Timestamp | The current time in Unix seconds |
X-Naumu-Signature | sha256= followed by the hex HMAC (below) |
The signature is an HMAC-SHA256 over the string id.timestamp.body, keyed with the signing secret:
message = `${webhookId}.${timestamp}.${rawBody}`
signature = hex(HMAC-SHA256(signingSecret, message))Send the result as X-Naumu-Signature: sha256=<hex>.
The timestamp must be within five minutes of Naumu's clock - this defeats anyone replaying a delivery they captured earlier. The signature is checked against the raw bytes you sent, so don't re-serialize the body between signing and sending.
Manage a webhook
Each row in the list shows the webhook's name, its URL with a copy button, who its deliveries reach, and the first lines of its instructions. From the row you can:
- Toggle it on or off - a paused webhook stops acting on deliveries without losing its URL or secret.
- Edit it - the pencil reopens the same dialog. Name, instructions, and the auto-file switch save when you select Save; the Home controls save as you change them.
- Rotate its signing secret - the key icon generates a fresh secret, shown once. The old secret stops verifying immediately, so update your caller right after.
- Delete it - the URL stops accepting deliveries at once. Anything still POSTing to it gets an error. This cannot be undone.
The URL is the whole credential for posting into a webhook, so Naumu shows it only to people who can manage the webhook. A member who reaches the row through the space or a shared topic sees that the webhook exists, and what it does, without its URL.
Related
- Agents - the AI participants an inbound webhook's deliveries run as.
- Routines - standing work on a schedule, configured with the same sharing controls.
- External agents - the reverse direction: Naumu signs outbound webhooks to your own agent runtime.