Voice agent · Custom HTTP guide · Conversation-initiation webhook + post-call webhook

Northsun + ElevenLabs

ElevenLabs' documented conversation-initiation webhook (its docs also call this "Twilio personalization" or the "pre-call webhook") and post-call webhook cover the inbound-phone lifecycle for an ElevenLabs Agent. This guide maps those events to Northsun through your server; it is a custom HTTP guide, not a native or certified adapter.

What Northsun adds to ElevenLabs

• Inbound context before the agent speaks.

  ElevenLabs' documented conversation-initiation webhook fires before the agent's first utterance on native-Twilio-imported and SIP-trunk inbound calls.

• HMAC-verified write-back.

  Verify the elevenlabs-signature header on the post-call webhook before mapping call data into Northsun.

• Honest outbound handling.

  For outbound calls, Register Call, and SDK sessions, run recall in your own code before starting the session — ElevenLabs never initiates a hook for that path.

How to connect ElevenLabs to Northsun

1. 1

   Configure the conversation-initiation webhook

   Follow ElevenLabs' current dashboard configuration and enable the system-prompt and first-message overrides your response depends on.

2. 2

   Return the client_data envelope

   Call Northsun, then return conversation_initiation_client_data with only the dynamic_variables your agent's prompt uses.

3. 3

   Configure the post-call webhook

   Verify the elevenlabs-signature HMAC and map the current post_call_transcription payload into Northsun's calls/end schema.

4. 4

   Test both call directions

   Inbound and outbound/Register Call setups are different paths. 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) {
  // Conversation-initiation webhook: verify your configured shared-secret header first.
  const payload = await request.json();
  const packet = await callNorthsun("/v1/recall_and_enrich", {
    phone_number: payload.caller_id,
    trigger: "answered",
    session_id: payload.call_sid,
  });

  return Response.json({
    type: "conversation_initiation_client_data",
    dynamic_variables: {
      caller_name: String(packet.caller?.name ?? "there"),
      caller_summary: String(packet.memory?.summary ?? ""),
    },
  });
}

// In your verified post-call webhook handler (elevenlabs-signature HMAC):
await callNorthsun("/v1/calls/end", normalizedCallEnd(postCallPayload));

FAQ

Is this a native ElevenLabs integration?

No. It is a custom HTTP mapping maintained in your own application against ElevenLabs' documented webhook contract.

Does this cover the web widget?

No. The web widget has no phone number, and Northsun recall is phone-keyed, so it is out of scope for this guide.

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 ElevenLabs mapping is correct — verify with a later recall in your own integration.

Choose Northsun as your agent memory layer.