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 - called an event trigger in the app - turns an outside event - a GitHub issue, a Stripe charge, a form submission, anything that can send an HTTP request - into agent action inside one of your spaces. You give the external system a private URL to POST to; 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.
Event triggers belong to a space, not to your account. Open the space's settings, go to Integrations, and find the Event triggers & webhooks section. Creating and managing triggers is reserved for space admins.
Create an event trigger
Select New event trigger. 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 trigger reads as Untitled trigger.
- Set its Home - who the deliveries reach - with the same sharing controls a note or a responsibility 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 trigger - keeps every delivery where the trigger 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 trigger'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 trigger's Home exactly - a delivery never reaches anyone who could not already see the trigger.
- 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 trigger'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 an event trigger
Each row in the list shows the trigger'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 trigger 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 trigger, so Naumu shows it only to people who can manage the trigger. A member who reaches the row through the space or a shared topic sees that the trigger exists, and what it does, without its URL.
Related
- Agents - the AI participants an inbound webhook's deliveries run as.
- Scheduled tasks - 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.