Voice agent · Custom HTTP guide · Server URL events

Northsun + Vapi

Vapi's current Server URL documentation defines assistant-request for dynamic inbound assistant selection and end-of-call-report for completed-call artifacts. This guide maps those events to Northsun through your server; it is not a native or certified adapter.

What Northsun adds to Vapi

• Deadline-aware inbound recall.

  Vapi documents a fixed 7.5-second end-to-end response limit for assistant-request; your full handler must be tested inside it.

• Separated write-back.

  Normalize end-of-call-report only after verifying the current Vapi artifact and request-authentication contract.

• Honest outbound handling.

  For outbound calls, run recall in your own orchestration before creating the call and pass selected values through Vapi's current override mechanism.

How to connect Vapi to Northsun

1. 1

   Configure one Server URL

   Follow Vapi's official Server URL documentation and enable only the events your handler processes.

2. 2

   Handle assistant-request

   Read the current Call Object, perform a deadline-bounded Northsun recall, and return the minimum assistant response Vapi requires.

3. 3

   Handle end-of-call-report

   Verify the request and map the current artifact messages into Northsun transcript roles and timestamps.

4. 4

   Test both directions

   Inbound and outbound setup are different. Record a controlled proof for each direction you support.

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();
}

export async function POST(request: Request) {
  const { message } = await request.json();

  if (message.type === "assistant-request") {
    const phoneNumber = message.call?.customer?.number;
    if (!phoneNumber) return Response.json({});

    const packet = await callNorthsun("/v1/recall_and_enrich", {
      phone_number: phoneNumber,
      trigger: "ringing",
      session_id: message.call?.id,
    });

    return Response.json({
      assistantId: process.env.VAPI_ASSISTANT_ID,
      assistantOverrides: {
        variableValues: {
          caller_name: packet.caller?.name ?? "there",
          caller_summary: packet.memory?.summary ?? "",
        },
      },
    });
  }

  if (message.type === "end-of-call-report") {
    // Verify the Vapi request, then normalize the current artifact shape.
    await callNorthsun("/v1/calls/end", normalizedCallEnd(message));
  }

  return Response.json({ received: true });
}

FAQ

Is this a native Vapi integration?

No. It is a custom Server URL mapping maintained in your application.

What does the 7.5-second limit mean?

It is Vapi's documented end-to-end assistant-request limit, not a Northsun latency benchmark. Test your network and full handler.

Does one successful webhook prove write-back?

Yes for the interaction itself: a Northsun 204 confirms it is already committed durably in the database. It does not prove your Vapi mapping is correct — verify with a later recall in your own integration.

Choose Northsun as your agent memory layer.