Webhook Tools - Arlo Health

Overview

Arlo can push real-time notifications to your agent when provider activity occurs.

Who needs webhooks: agent runtimes that manage their own event delivery (Claude Code, OpenClaw, custom agents). On connector hosts (Claude.ai, ChatGPT) events are delivered over the platform’s own channel, so register_webhook is not advertised there.Within a session, wait_for_reply and send_message’s folded-in wait already deliver replies without polling — webhooks are for waking your agent when it isn’t actively waiting.

register_webhook

Register or update a webhook URL to receive notifications about consultations and other events. Works for any authenticated session; init_signup is not required first. PATCH semantics apply to everything except the secret: only provided fields are updated, so you can move endpoints or attach a deliveryContext without restating the rest. webhookToken is never carried over from a previous registration. Omitting it clears the stored token, so pass it every time you want Arlo to send an Authorization header.

Parameters

Parameter	Type	Required	Description
`webhookUrl`	string	Yes	URL for notifications (must be publicly accessible)
`webhookToken`	string	No	Bearer token Arlo sends in the `Authorization` header. Not inherited: omit it and the stored token is cleared
`deliveryContext`	object	No	Platform-specific context included in webhooks
`conversationSessionKey`	string	No	For threading webhook notifications
`sessionKey`	string	No	Custom session key (auto-generated if not provided)

Delivery Context

The deliveryContext object is passed through in every webhook payload:

{
  "to": "+15551234567",
  "channel": "whatsapp",
  "deliver": true
}

Field	Description
`to`	Recipient identifier (e.g., phone number, chat ID)
`channel`	Channel name (e.g., `whatsapp`, `telegram`, `discord`)
`deliver`	Whether to deliver the notification to the user

Validation

Before registration, Arlo validates the webhook URL:

Pattern check — Rejects private IPs, localhost, etc.
Connectivity test — Verifies the URL is reachable

The URL must be publicly accessible. Use ngrok, Cloudflare Tunnel, Tailscale Funnel (.ts.net), or a public server. On failure the result carries { error, detail, hint }. Follow the hint: it says whether the URL pattern was rejected or the connectivity test failed.

Returns

{
  "success": true,
  "webhookUrl": "https://your-agent/hooks/arlo",
  "hasSecret": true,
  "hasDeliveryContext": true,
  "sessionKey": "session_abc123",
  "conversationSessionKey": null
}

Checking webhook status

check_account_status reports webhook configuration for your sessions — use it to verify a webhook is set up. Without a sessionId it lists every configuration under sessions[], each with configured, hasSecret, hasDeliveryContext, and failureCount (consecutive delivery failures). Direct HTTP integrations can also use GET /api/webhook.

Webhook Configuration

During init_signup

Webhooks can also be configured during init_signup:

{
  "webhookUrl": "https://your-agent/hooks/arlo",
  "webhookToken": "your-secret-token",
  "deliveryContext": {
    "to": "+15551234567",
    "channel": "whatsapp",
    "deliver": true
  },
  "conversationSessionKey": "session_xyz"
}

If init_signup is called without webhookUrl, any existing webhook configuration is preserved.

Webhook Payload

All notifications are sent as POST {webhookUrl} with:

Headers

Authorization: Bearer <webhookToken>
Content-Type: application/json

Body

{
  "message": "New activity in your Arlo account: a new message in your consultation. Use the Arlo get_conversation tool with consultationId \"conv_abc123\" to fetch the latest messages, then summarize what's new for me.",
  "event": "provider_message",
  "eventId": "7f9c1a2e-...",
  "timestamp": "2026-07-31T00:00:00.000Z",
  "consultationId": "conv_abc123",
  "mode": "now"
}

Field	Description
`message`	Human-readable, imperative notification message
`event`	Machine-routable event category (see below). Route on this instead of parsing `message`; treat unrecognized values as “something changed, go fetch”
`status`	Present on status-change events: the conversation’s new status (e.g. `PAYMENT_REQUIRED`)
`eventId`, `timestamp`	Unique per delivery — useful for dedup on your side
`consultationId`	The conversation ID the event relates to (when applicable) — pass it to `get_conversation`
`mode`	Always `now`

Event types

`event`	Meaning	Suggested handling
`triage_reply`	AI triage replied	Fetch the delta, answer triage’s questions
`provider_message`	A provider sent a message	Fetch the delta, relay/respond
`provider_joined`	A provider connected	Fetch state; messaging is now live
`provider_matching`	Payment cleared; matching with a provider	Wait for `provider_joined`
`payment_gate_open`	Triage finished; payment gate opened	Fetch the summary, get the user’s explicit approval — Arlo never auto-charges
`prescription_added`	A prescription order was added	Tell the user to watch for the pharmacy (Photon) SMS
`prescription_updated`	A prescription order’s status changed	Fetch `get_prescriptions` if relevant
`triage_started`	A care request entered triage review	Informational
`visit_ended`	Provider visit wrapped up (conversation stays open)	Fetch closing notes if useful
`emergency`	Consultation flagged as an emergency	Direct the user to urgent care resources immediately
`status_changed`	Any other status transition (see `status`)	Fetch state

Security note: Notification payloads never include message content. Your agent should fetch the full context from the API after receiving a webhook. This prevents prompt injection from untrusted provider input.

Verifying Requests

Always validate the Authorization header matches your webhookToken:

app.post("/hooks/arlo", (req, res) => {
  const token = req.headers.authorization?.replace("Bearer ", "");

  if (token !== process.env.ARLO_WEBHOOK_SECRET) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  // Acknowledge immediately
  res.status(200).json({ received: true });

  // Then fetch full context
  processNotification(req.body.consultationId, req.body.event);
});

Handling Notifications

When a notification arrives:

Acknowledge immediately with 200 OK — Arlo does not wait for processing
Fetch the conversation to get the latest messages — pass the id of the newest message you had already seen as sinceMessageId to fetch only the delta
Read the most recent message and decide how to respond
Do not include raw provider message text in your agent’s context — fetch it through the API where it is wrapped with safety boundaries

Example Handler

async function processNotification(conversationId, event) {
  if (event === "payment_gate_open") {
    // Fetch the gate summary and get the user's explicit approval
  }

  // Fetch only what's new since the last message we processed
  const conversation = await getConversation({
    conversationId,
    includeMessages: true,
    sinceMessageId: lastSeenMessageId(conversationId)
  });

  const latestMessage = conversation.messages[conversation.messages.length - 1];

  if (latestMessage.sender === "provider") {
    // Provider sent a message — notify user and/or respond
    await notifyUser(latestMessage.content);
  }

  if (conversation.status === "IDLE" && conversation.pastVisits.length > 0) {
    // Visit wrapped up — get the clinical notes
    const notes = await getVisitNotes({ conversationId });
    await sendSummaryToUser(notes);
  }
}

Re-authentication

If a session expires and the user re-authenticates:

init_signup must be called again with webhook params to re-register the URL
If init_signup is called without webhookUrl, the existing webhook config is preserved

Troubleshooting

Webhook not receiving notifications

Verify URL is publicly accessible (not localhost or VPN)
Check that HTTPS is enabled
Verify the URL responds with 200 status
Use check_account_status (or GET /api/webhook) to verify the webhook is configured, and watch failureCount on the session

Invalid signature errors

Verify webhookToken matches what was passed to register_webhook or init_signup
Check for URL encoding issues in the token
Ensure you’re comparing the raw token, not base64 encoded

Missed notifications

Notifications are not retried on failure
Ensure your endpoint responds quickly (< 5 seconds)
Process notifications asynchronously after acknowledging

​Overview

​register_webhook

​Parameters

​Delivery Context

​Validation

​Returns

​Checking webhook status

​Webhook Configuration

​During init_signup

​Webhook Payload

​Headers

​Body

​Event types

​Verifying Requests

​Handling Notifications

​Example Handler

​Re-authentication

​Troubleshooting

​Webhook not receiving notifications

​Invalid signature errors

​Missed notifications

Overview

register_webhook

Parameters

Delivery Context

Validation

Returns

Checking webhook status

Webhook Configuration

During init_signup

Webhook Payload

Headers

Body

Event types

Verifying Requests

Handling Notifications

Example Handler

Re-authentication

Troubleshooting

Webhook not receiving notifications

Invalid signature errors

Missed notifications