Events
Nocturnal tells other apps and agents when something it does is ready, fails or needs you: an agent finished, a deploy went live, CI broke, a plan phase is blocked. Anyone you allow can subscribe, and Nocturnal does not need to know who they are. It also takes in events from your other apps, so one piece of work can be followed from app to app and computer to computer.
You set this up through the MCP server. Ask your assistant, for example: "Send Nocturnal's agent and release events to my CRM's inbox."
What an event looks like
Every event, sent or received, is one JSON envelope:
{
"specversion": "event/1",
"id": "evt_3f1c…",
"type": "agent.done",
"occurredAt": "2026-11-10T09:12:00.000Z",
"source": { "app": "nocturnal", "device": "Studio Mac" },
"traceId": "trc_9a2e…",
"parentEventId": "evt_77b0…",
"subject": { "kind": "agent", "id": "…", "title": "Fix the login wall", "url": "https://nocturnal.sh/dashboard?project=…" },
"line": "“Fix the login wall” finished on nocturnal.",
"status": "ok",
"data": { "projectId": "nocturnal", "runMode": "agent", "durationMs": 182000 }
}
- id is unique and stable: if the same event reaches you twice, it has the same id.
- status is
ok, failed, waiting (it needs a person) or info.
- traceId names the chain of work this belongs to; parentEventId is the event that caused it.
- Events carry ids, titles and one plain sentence. They never carry prompts, transcripts, code, logs, tokens or personal records.
Subscribing
subscribe_events takes a public https address, the events you want and an optional label and trace. Events can be exact types (release.live), prefixes (agent.*) or * for everything. Your assistant shows you one line saying where your events will go. Nothing is sent until you agree. The answer includes a secret, shown only once.
Each delivery is a POST with the envelope as the body and these headers:
| Header | Value |
|---|
X-Event-Type | The event type |
X-Event-Id | The event id; dedupe on it |
X-Event-Timestamp | Unix seconds |
X-Event-Signature | v1= + hex HMAC-SHA256 of "<timestamp>.<raw body>" with your secret |
Check the signature against the raw body before parsing it, and refuse timestamps more than five minutes off.
Answer with any 2xx. A 5xx, a 429, or no answer within 10 seconds is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then dropped. Any other answer is taken as a no and is not retried. Redirects are not followed. Five failed deliveries in a row switch the subscription off, and Nocturnal sends webhook.disabled so you find out.
event_deliveries shows each attempt and its answer. unsubscribe_events switches a subscription off. Private, loopback and internal addresses are refused.
Receiving events from other apps
create_event_inbox gives a named app (for example fruitful) an inbox. After you agree, it answers once with the inbox address and a token:
https://nocturnal.sh/events/in/<inboxId>
The app POSTs one envelope, or an array of up to 50, with Authorization: Bearer <token>. An app that can only be given a web address can use https://nocturnal.sh/events/in/<inboxId>/<token> instead. If it sends X-Event-Signature, Nocturnal checks it against the token, or against the app's own signing secret once you register it with update_event_inbox. A signature that doesn't match is refused. The same event sent twice is stored once. The inbox answers 202 as soon as the events are stored.
list_inbox_events shows what arrived. A new inbox for the same app replaces its old one.
Following one piece of work
When Nocturnal does work because of an event, or because a request named a traceId, everything that work produces carries the same traceId, with parentEventId pointing at its cause. It only starts a new trace when it wasn't given one.
To act on an incoming event, pass its traceId, and its id as parentEventId, to agent_new, plan_build, script_run, release_run or any other tool that starts work. list_inbox_events hands you both. An agent Nocturnal starts gets them as NOCTURNAL_TRACE_ID and NOCTURNAL_PARENT_EVENT_ID, so it can pass them on to your other apps. Agents Nocturnal starts can read events, but they can't create subscriptions or inboxes.
event_trace lists every event Nocturnal sent or received on one trace, oldest first.
Every event Nocturnal sends
Agents
| Event | Status | Subject | When | Data |
|---|
agent.started | info | agent | An agent run started: a new chat, a follow-up, a queued run, a loop pass, a plan phase or a scheduled job. | projectId, projectName, runMode, model, provider |
agent.done | ok | agent | An agent run finished and is not waiting on anyone. | projectId, projectName, runMode, model, durationMs |
agent.waiting | waiting | agent | An agent run stopped to ask the person something: a question, a permission it was denied, or a NEEDS-INPUT marker. | projectId, projectName, runMode |
agent.failed | failed | agent | An agent run ended in an error: sign-in expired, usage limit, credits, a crash, or no response. | projectId, projectName, reason, exitCode |
agent.stopped | info | agent | A person stopped a running agent. | projectId, projectName |
Plans
| Event | Status | Subject | When | Data |
|---|
plan.created | info | plan | A plan was created on a project. | projectId, projectName |
plan.started | info | plan | A plan started building: the whole plan in one run, or its first phase. | projectId, projectName, sessionId |
plan.built | ok | plan | A plan finished building: every phase is done, or the whole-plan build ended. | projectId, projectName |
stage.done | ok | stage | One phase of a plan finished. | projectId, projectName, planId, planTitle, sessionId |
stage.failed | failed | stage | One phase of a plan failed. | projectId, projectName, planId, planTitle, sessionId |
stage.blocked | waiting | stage | One phase of a plan is blocked and needs a person before the build can go on. | projectId, projectName, planId, planTitle, sessionId |
plan.reviewed | ok | plan | A review pass on a plan finished, whether it revised the plan or left it unchanged. | projectId, projectName, outcome |
proposal.waiting | waiting | proposal | An agent proposed roadmap changes; they wait for a person to accept or reject them. | projectId, projectName, changes, sessionId |
proposal.accepted | ok | proposal | A person accepted a roadmap proposal (all of it or some changes). | projectId, projectName, applied, outcome |
proposal.rejected | info | proposal | A person rejected a roadmap proposal. | projectId, projectName |
request.submitted | waiting | plan-request | A client submitted a plan request (their scope); it waits for review. | projectId, projectName |
request.accepted | ok | plan-request | A plan request was accepted and became a plan. | projectId, projectName, planId |
Processes
| Event | Status | Subject | When | Data |
|---|
process.started | info | process | A managed long-running process (a dev server, a worker) was started. Automatic restarts are not reported. | projectId, projectName |
process.crashed | failed | process | A managed process exited without being asked to. Reported once per crash streak; Nocturnal keeps restarting it. | projectId, projectName, restarts |
process.stopped | info | process | A managed process was stopped on request. | projectId, projectName |
Scripts
| Event | Status | Subject | When | Data |
|---|
script.done | ok | script | A project script (build, test, deploy, …) finished with exit code 0. | projectId, projectName, scriptId, runId, exitCode |
script.failed | failed | script | A project script failed or was stopped before it finished. | projectId, projectName, scriptId, runId, exitCode |
Git
| Event | Status | Subject | When | Data |
|---|
commit.created | ok | commit | A commit was made through Nocturnal (the dashboard, the CLI or a tool call). | projectId, projectName, branch |
branch.created | info | branch | A branch was created through Nocturnal. | projectId, projectName |
branch.pushed | ok | branch | A branch was pushed to its remote through Nocturnal. | projectId, projectName |
branch.merged | ok | branch | A branch was merged into the current one through Nocturnal. | projectId, projectName, into |
merge.conflicted | waiting | branch | A pull or merge stopped on conflicts that a person (or an agent they send) has to resolve. | projectId, projectName, files |
GitHub
| Event | Status | Subject | When | Data |
|---|
pr.opened | info | pull-request | A pull request was opened through Nocturnal. | repo, head, base |
pr.merged | ok | pull-request | A pull request was merged through Nocturnal. | repo |
ci.passed | ok | ci-run | A GitHub Actions run on a watched project completed successfully. | projectId, projectName, branch, commit, workflow |
ci.failed | failed | ci-run | A GitHub Actions run on a watched project completed without succeeding. | projectId, projectName, branch, commit, workflow, conclusion |
Issues
| Event | Status | Subject | When | Data |
|---|
issue.created | info | issue | A GitHub issue was filed through Nocturnal. | repo, number |
issue.closed | ok | issue | A GitHub issue was closed through Nocturnal. | repo, number |
issue.commented | info | issue | A comment was added to a GitHub issue through Nocturnal. | repo, number |
Versions
| Event | Status | Subject | When | Data |
|---|
version.cut | ok | version | A version was cut and its changelog entry written. | projectId, projectName, version |
version.deployed | ok | version | A version was marked as deployed to an environment. | projectId, projectName, version, environment |
Deploys
| Event | Status | Subject | When | Data |
|---|
release.started | info | release | A deploy to a target started. | projectId, projectName, target, production |
release.live | ok | release | A deploy to a production target succeeded: the change is live. | projectId, projectName, target |
release.deployed | ok | release | A deploy to a non-production target (staging, test) succeeded. | projectId, projectName, target |
release.failed | failed | release | A deploy failed or was interrupted. | projectId, projectName, target, production |
preview.ready | ok | preview | A preview deploy of a chat's work is up. | projectId, projectName, sessionId, provider |
preview.failed | failed | preview | A preview deploy of a chat's work failed. | projectId, projectName, sessionId |
Jobs
| Event | Status | Subject | When | Data |
|---|
job.created | info | job | A scheduled job was created. | projectId, projectName |
job.ran | info | job | A scheduled job fired and started its agent. The agent's own events follow on the same trace. | projectId, projectName, sessionId |
job.failed | failed | job | A scheduled job was due but could not start its agent. | projectId, projectName |
Projects
| Event | Status | Subject | When | Data |
|---|
project.created | info | project | A project was created or imported. | — |
project.adopted | ok | project | A project was adopted: Nocturnal wrote its .nocturnal/project.json. | — |
project.archived | info | project | A project was archived. | — |
Brain
| Event | Status | Subject | When | Data |
|---|
brain.refreshed | ok | brain | A Brain refresh finished: what the project knows about itself was re-read. | projectId, projectName, outcome, facts |
brain.failed | failed | brain | A Brain refresh failed or was interrupted. | projectId, projectName |
decision.recorded | info | decision | A decision was recorded in a project's Brain. | projectId, projectName |
Changes
| Event | Status | Subject | When | Data |
|---|
change.verified | ok | change | A person marked a change as working. | projectId, projectName |
change.problem | failed | change | A person reported a problem with a change. | projectId, projectName |
Sync
| Event | Status | Subject | When | Data |
|---|
sync.conflict | waiting | plan | A plan was edited on two computers at once; a person has to choose which version to keep. | projectId, projectName |
Usage
| Event | Status | Subject | When | Data |
|---|
usage.high | info | usage-window | A Claude or ChatGPT plan window crossed 80% used. | provider, window, usedPercent, resetsAt |
usage.limited | waiting | usage-window | A Claude or ChatGPT plan window hit its limit; agents on it wait until it resets. | provider, window, resetsAt |
Billing
| Event | Status | Subject | When | Data |
|---|
trial.started | info | account | A Nocturnal Pro trial started on the account. | — |
payment.received | ok | account | A Nocturnal Pro payment went through. | periodEnd |
payment.failed | failed | account | A Nocturnal Pro payment failed; the card needs attention. | — |
pro.cancelled | info | account | Nocturnal Pro was cancelled; it runs to the end of the paid period and does not renew. | periodEnd |
pro.ended | info | account | Nocturnal Pro ended on the account. | — |
Events
| Event | Status | Subject | When | Data |
|---|
webhook.disabled | waiting | event-subscription | An event subscription was switched off after five failed deliveries in a row; it needs a person to fix the address and subscribe again. | url, label |