Receive webhooks on localhost

Your handler runs on http://localhost:3000; OnCore delivers over the public internet and cannot reach it. A tunnel closes that gap: it gives your machine a public HTTPS address and forwards every request straight to your local port, which also puts you close enough to read each delivery byte for byte.

Overview#

You will publish your local port behind a public HTTPS URL, set that URL as one assistant's serverUrl, and place a call to prove the round trip. Reading the raw request, replaying it, and putting the assistant back afterwards all hang off that loop.

A delivery does not change because it travelled through a tunnel. It is the same POST, the same JSON body, and the same headers described in the webhooks overview. The handler you get working this way is therefore the handler you deploy.

Prerequisites#

• Something listening on a local port. Any HTTP server that answers POST with a 2xx will do; Receive call results on your server builds one from scratch if you have none.
• An API key, to change the assistant's configuration. Authentication covers how keys are sent.
• Your client server secret, from the API Keys page. This is the inbound credential: every delivery carries it and your handler compares against it. It is not the key you authenticate API calls with.
• An assistant you can repoint, and a way to call it: a phone number attached to it, or browser calling from a web page. Repointing sends that assistant's live deliveries to your machine, so use one you are testing with, and expect to collide with any teammate tunnelling the same assistant.

Tunnel a delivery to your machine#

node server.mjs
# listening on :3000

ngrok http 3000

curl -X PATCH https://core-api.heysadie.ai/assistants/0195f1e2-0000-0000-0000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "serverUrl": "https://a1b2c3d4.ngrok.app/oncore/webhooks" }'

app.post("/oncore/webhooks", express.json(), (req, res) => {
  console.log("[webhook] hit", {
    type: req.body?.type,
    secret: req.header("x-sadie-core-secret") ? "present" : "MISSING",
  });
  // …verify, then respond
});

Read the raw delivery#

The tunnel sees the request before your framework touches it, so an inspector there shows what OnCore actually sent rather than what your parser made of it. ngrok runs one at http://127.0.0.1:4040, listing the method, every header, and the body of each forwarded request; check your own tunnel's documentation for the equivalent.

Capturing the request yourself works with any tunnel and leaves you a file to replay. This listens on the same port as your handler, so run one or the other, not both:

npm install express
node capture.mjs

import { writeFileSync } from "node:fs";
import express from "express";

const app = express();

// Raw body, not express.json(): a signature can only be checked against the
// exact bytes, and re-serialising the parsed object changes them.
app.post("/oncore/webhooks", express.raw({ type: "*/*" }), (req, res) => {
  if (!Buffer.isBuffer(req.body)) return res.status(200).end();

  const stamp = Date.now();
  writeFileSync(`delivery-${stamp}.headers.json`, JSON.stringify(req.headers, null, 2));
  writeFileSync(`delivery-${stamp}.body.json`, req.body);
  console.log("[webhook] captured", stamp, req.body.length, "bytes");
  res.status(200).end();
});

app.listen(3000, () => console.log("listening on :3000"));

The field tables on each event page tell you what the body should contain; end-of-call report is the one most integrations start with.

Replay a delivery instead of placing another call#

Placing a call for every edit is a slow loop, and OnCore's public API exposes no endpoint that re-sends a past delivery. Replay is therefore something you drive locally, in one of two ways:

1. Your tunnel's own replay, if it has one: ngrok's inspector re-sends any captured request to your port with the same method, headers, and body.
2. curl straight at your local port, bypassing the tunnel entirely. This is the fastest loop and it works with the tunnel switched off.

For a delivery carrying the plaintext secret (voice, messaging, and tool events), the secret header is the only one your handler cares about:

curl -X POST http://localhost:3000/oncore/webhooks \
  -H "Content-Type: application/json" \
  -H "x-sadie-core-secret: YOUR_CLIENT_SERVER_SECRET" \
  --data-binary @delivery-1735689600000.body.json

For a signed WhatsApp event, pass the captured signature and delivery headers through unchanged, and send the original bytes unedited; the signature covers exactly those bytes, so reformatting the JSON, even only its whitespace, invalidates it:

curl -X POST http://localhost:3000/oncore/whatsapp-webhooks \
  -H "Content-Type: application/json" \
  -H "X-OnCore-Signature: sha256=CAPTURED_SIGNATURE_HEX" \
  -H "X-OnCore-Delivery: 0195f1e2-0000-0000-0000-000000000000" \
  --data-binary @delivery-1735689600000.body.json

Signed events are the retried ones, so a handler for them should be deduplicating on X-OnCore-Delivery, and a replay reuses that id, which is exactly what such a handler is built to ignore. Clear the store between replays, or you will conclude your handler is broken when it is working.

When nothing arrives#

Rule out the local-only causes first, then work through Webhooks not arriving for the rest.

Put the assistant back#

An assistant left pointing at a tunnel that is no longer running is worse than one never repointed: voice and messaging deliveries are not retried, so those webhooks are never seen. Clear the override when you finish, which returns the assistant to the default server URL for your account:

curl -X PATCH https://core-api.heysadie.ai/assistants/0195f1e2-0000-0000-0000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "serverUrl": null }'

The calls themselves are not lost with the webhooks. Every call you placed while testing (and every one that went to a dead tunnel) is still readable from the calls API, transcript and summary included, so you can backfill whatever your handler missed.

Next steps#

• Webhooks overview: the two delivery models and the verification code for each.
• Webhooks not arriving: the general debugging path, once the tunnel is ruled out.
• Receive call results on your server: build the receiver this page tunnels to.
• End-of-call report: the payload your local handler will be reading.