Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nomos.energy/llms.txt

Use this file to discover all available pages before exploring further.

To receive real-time events from Nomos, run an HTTPS endpoint that accepts signed POST requests, register it in the dashboard, and dispatch on the events you care about.
1

Create a development endpoint

In your local app, add a route that accepts POST requests and responds with 2xx.
pages/api/webhooks.ts
export default (req, res) => {
  if (req.method === "POST") {
    const event = req.body;
    console.log(event);
    res.status(200).end();
  }
};
Anything other than 2xx is treated as a failure and triggers retries.
Expose your local endpoint with a tunnel like ngrok or VS Code Port Forwarding so the dashboard can reach it.
2

Register the endpoint in Nomos

Open the Webhooks page in the Nomos dashboard and add a new webhook:
  1. Paste your publicly accessible HTTPS URL.
  2. Select the events you want to subscribe to.
Saving generates a signing secret. You’ll need it to verify requests in step 4.
3

Send a test delivery

From the webhook’s detail page, trigger a test event. The payload follows the standard envelope:
{
  "id": "evt_test_abc123",
  "timestamp": "2026-04-30T12:00:00.000Z",
  "topic": "test.event",
  "context": {}
}
Confirm your endpoint logs the request and returns 2xx.
4

Verify and handle real events

Before acting on an event, validate the signature header so you only process real Nomos deliveries. See Verify webhook requests for the full procedure.Then dispatch on topic. The context only carries IDs, so fetch the resource when you need its current state.
pages/api/webhooks.ts
export default async (req, res) => {
  if (req.method !== "POST") return res.status(405).end();

  const event = req.body;

  switch (event.topic) {
    case "subscription.created":
      // event.context.subscription is the ID
      break;
    case "subscription.confirmed":
      // ...
      break;
  }

  res.status(200).end();
};
5

Deploy and register the production endpoint

Deploy your handler, then add a second webhook in the dashboard pointing at the production URL. You’ll get a separate signing secret for the production endpoint.