Voice agent · Custom HTTP guide · Inbound webhook + signed call events

Northsun + Retell

Retell documents an inbound webhook that can supply string dynamic variables before an inbound call connects, plus signed call-event webhooks including call_analyzed. This guide maps those capabilities to Northsun through your server; no native adapter is implied.

What Northsun adds to Retell

• Inbound dynamic context.

  Retell's documented inbound webhook can return string dynamic variables before the call object exists.

• Signed event handling.

  Verify x-retell-signature before mapping call events into Northsun.

• Explicit write-back proof.

  The 204 confirms the interaction is already committed durably; verify with a later recall to prove your own Retell mapping.

How to connect Retell to Northsun

1. 1

   Configure the inbound webhook

   Follow Retell's current phone-number configuration and preserve its documented 10-second timeout and retry behavior in your design.

2. 2

   Return string variables

   Call Northsun with from_number and return only string-valued dynamic_variables used by the agent.

3. 3

   Configure signed call events

   Enable the event you need, verify x-retell-signature, and normalize the current Call Object into Northsun's calls/end schema.

4. 4

   Test failure fallbacks

   Prove how the call behaves when Northsun returns partial enrichment, a timeout, or a retryable server error.

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) {
  // Verify x-retell-signature before trusting this body.
  const payload = await request.json();

  if (payload.event === "call_inbound") {
    const phoneNumber = payload.call_inbound?.from_number;
    const packet = await callNorthsun("/v1/recall_and_enrich", {
      phone_number: phoneNumber,
      trigger: "ringing",
    });

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

  if (payload.event === "call_analyzed") {
    await callNorthsun("/v1/calls/end", normalizedCallEnd(payload.call));
  }

  return new Response(null, { status: 204 });
}

FAQ

Is this a native Retell integration?

No. It is a custom HTTP mapping using Retell's documented inbound and call-event webhooks.

Must dynamic variables be strings?

Yes. Retell's current documentation requires string values for dynamic variables.

How is the webhook authenticated?

Verify Retell's x-retell-signature with the current official verification procedure before processing the body.

Choose Northsun as your agent memory layer.