Telephony · Custom HTTP guide · Voice URL webhook + Status Callback

Northsun + Twilio

Twilio's documented Voice URL webhook and Status Callback webhook cover raw TwiML telephony — no assistant, no agent concept, no vendor LLM. This guide maps those two events to Northsun's frozen caller-memory API through your own server; it is a custom HTTP guide, not a native or certified adapter.

What Northsun adds to Twilio

• A caller-memory lookup you control.

  Your Voice URL handler decides when to call Northsun and what to do with the response — there is no vendor response envelope to fill in.

• Explicit normalization.

  Twilio's form-encoded webhook body maps into the frozen Northsun request shape; test that mapping with controlled calls before production.

• A proofable boundary.

  A successful recording proves the exact Voice URL and Status Callback configuration shown; it does not establish a native adapter.

How to connect Twilio to Northsun

1. 1

   Configure the Voice URL

   Point your Twilio phone number's (or TwiML App's) Voice URL at your handler and verify X-Twilio-Signature before trusting the request.

2. 2

   Recall before you build TwiML

   Call POST /v1/recall_and_enrich with the caller's number and CallSid, then use the response to shape the TwiML you return.

3. 3

   Configure the Status Callback

   Point the Status Callback URL at a verified handler and write back only on a terminal CallStatus (completed, busy, failed, no-answer, canceled).

4. 4

   Prove the write-back

   The interaction is committed durably before calls/end responds; retain the Northsun trace ID and confirm it with a later recall.

Custom HTTP pattern

Adapt this boundary to the current vendor payload and verify it with controlled events before production.

async function callNorthsun(path: string, body: unknown) {
  const response = await fetch(`https://mcp.northsun.ai${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NORTHSUN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    throw new Error(`Northsun request failed: ${response.status}`);
  }

  return response.status === 204 ? undefined : response.json();
}

// In your Voice URL webhook handler, after verifying X-Twilio-Signature:
const packet = await callNorthsun("/v1/recall_and_enrich", {
  phone_number: callerNumber,
  trigger: "answered",
  session_id: callSid,
});

// Return your own TwiML using packet.caller / packet.memory here.

// In your verified Status Callback handler, on a terminal CallStatus:
await callNorthsun("/v1/calls/end", {
  phone_number: callerNumber,
  session_id: callSid,
  duration_s: durationSeconds,
  outcome: mappedOutcome,
});

FAQ

Is this a native Twilio integration?

No. It is a custom HTTP mapping between documented Twilio webhook capabilities and Northsun's frozen REST endpoints.

Does Twilio send a transcript?

No. Twilio's Status Callback carries no transcript field — Twilio does not perform ASR on this path. Pass your own transcript only if your application assembled one.

Is this the same as the enrichment vendor Twilio Lookup?

No. Twilio Lookup is a caller-ID enrichment vendor Northsun calls server-side on every recall. This guide is for wiring raw Twilio telephony (TwiML/Media Streams) itself, a separate integration.

Choose Northsun as your agent memory layer.