Run a local server

Write a webhook receiver that keeps the raw body for verification, and give it a public URL that Signals can reach.

Complexity
2/5
Clients
Node.js
Time
10 minutes

Signals posts each event to a URL you own. Run a small server that verifies and logs them.

Write the receiverServer-side

Install the dependencies:

npm install express standardwebhooks

The receiver keeps the body raw, because the signature covers the exact bytes Signals sent. It verifies the signature, answers 204 at once and then logs the event. Verify webhooks covers other languages and the checks.

server.ts
import express from 'express';
import { Webhook } from 'standardwebhooks';

const app = express();

app.post('/signals/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event: { type: string; data?: { patientRefId?: string; value?: number } };
  try {
    const webhook = new Webhook(process.env.SIGNALS_SIGNING_SECRET ?? '');
    event = webhook.verify(req.body, req.headers as Record<string, string>) as typeof event;
  } catch {
    return res.sendStatus(400);
  }
  res.sendStatus(204);
  console.log(event.type, event.data?.patientRefId, event.data?.value ?? '');
});

app.listen(3000, () => console.log('Listening on http://localhost:3000'));

Run it with npx tsx server.ts. Until you set SIGNALS_SIGNING_SECRET, it answers 400 to every delivery.

Get a public URLTerminal

Signals refuses a URL that resolves to a private address, such as localhost, so open a tunnel to port 3000. Any tunnel works:

cloudflared tunnel --url http://localhost:3000

or

ngrok http 3000

Both print an https:// address. Your webhook URL is that address plus /signals/webhook.

Forward events with ovok listenTerminal

ovok listen does not open a tunnel: it creates a temporary Signals webhook that posts to a public URL you give it, prints that webhook's signing secret, and removes the webhook when you quit. Use it to see deliveries arrive before you register a lasting subscriber.

npm install --global @ovok/cli
printf %s "$OVOK_MANAGER_SECRET" | ovok login --client-id "$OVOK_MANAGER_ID" --client-secret-stdin
ovok listen --signals-url https://<your-tunnel>/signals/webhook --signals-event 'alert.*'

Quit listen before you register the webhook, or your server receives each event twice.

Next

Register the webhook.

Last updated on

On this page