Webhook Tools

Webhooks notify agent runtimes about conversation activity, prescription orders, and care-job decisions, execution steps, and questions for the patient. They are intended for runtimes with a public HTTPS endpoint. Connector hosts do not advertise register_webhook.

`register_webhook`

Parameter	Type	Details
`webhookUrl`	string	Required publicly accessible URL
`webhookToken`	string	Optional bearer token sent in the `Authorization` header
`deliveryContext`	object	Optional platform-specific routing context
`conversationSessionKey`	string	Optional key for threading notifications
`sessionKey`	string	Optional session identifier

Arlo checks connectivity before saving the URL. The result contains success, webhookUrl, sessionKey, hasSecret, hasDeliveryContext, and conversationSessionKey.

Example response

{
    "success": true,
    "webhookUrl": "https://example.com/arlo/webhook",
    "sessionKey": "session_key_example",
    "hasSecret": true,
    "hasDeliveryContext": false,
    "conversationSessionKey": null
}

check_account_status reports webhook status for configured sessions. Call it without sessionId to inspect the account’s configurations.

Event payload

Arlo sends a POST request with an optional bearer token and a JSON body. Payload fields can include:

Field	Meaning
`event`	Event type
`eventId`, `timestamp`	Delivery identifiers
`status`	Conversation or care-job status when applicable
`consultationId`	Conversation ID for conversation events
`jobId`	Care job ID for `care_job_*` events
`askId`	The care team’s question, for `care_job_ask_*` events
`deliveryContext`	Routing context supplied at registration

Notifications contain no clinical message content. Fetch current data with get_conversation or get_care_jobs after receiving an event.

Event types

Event	Meaning	Follow-up
`triage_reply`	Arlo triage replied	Read the conversation and respond
`provider_message`	A provider sent a message	Read the conversation and relay or respond
`provider_joined`	A provider joined the conversation	Read the conversation
`provider_matching`	Visit approval completed and matching started	Await `provider_joined`
`payment_gate_open`	Triage reached the payment gate	Relay its summary and request patient approval
`prescription_added`	A prescription order was added	Read it with `get_prescriptions`
`prescription_updated`	A prescription order changed	Read it with `get_prescriptions`
`triage_started`	The conversation entered triage	Read the conversation
`visit_ended`	A provider visit ended	Read the conversation and visit notes
`emergency`	Triage identified an emergency	Direct the patient to urgent care
`status_changed`	Another conversation status transition	Read the conversation
`care_job_approved`	The patient approved a care job	Read it with `get_care_jobs` using `jobId`
`care_job_declined`	The patient declined a care job	Read its status
`care_job_expired`	30 days passed without the patient deciding	Create a new job if the patient still wants it
`care_job_updated`	The care team recorded an execution step	Read the audit trail
`care_job_executed`	The care team completed the action	Read the audit trail
`care_job_failed`	The care action failed	Read the audit trail
`care_job_ask_opened`	The care team needs answers from the patient	Read `openItems` with `get_care_jobs`, ask the patient, answer with `respond_to_care_job`
`care_job_ask_answered`	Answers were recorded, possibly by the patient on their portal	Nothing unless the patient asks
`care_job_ask_expired`	A question went unanswered past its deadline	Tell the patient; the job shows what happens next
`care_job_ask_withdrawn`	The care team no longer needs that answer	Nothing

Verify requests

Compare the Authorization bearer token with the webhookToken supplied to register_webhook. Acknowledge before fetching details:

async function handleNotification(req, res, sinceMessageId) {
    const token = req.headers.authorization?.replace(/^Bearer\s+/, "");
    if (token !== webhookToken) return res.sendStatus(401);

    res.sendStatus(200);

    if (req.body.event.startsWith("care_job_")) {
        await get_care_jobs({ jobId: req.body.jobId });
    } else {
        await get_conversation({
            conversationId: req.body.consultationId,
            sinceMessageId,
        });
    }
}

Handle a notification

Verify the Authorization bearer token and acknowledge immediately with 200 OK.
Fetch the conversation delta with get_conversation, passing the payload’s consultationId and your stored sinceMessageId. For a care_job_* event, call get_care_jobs with the payload’s jobId.
Do not put raw provider message text in the agent’s context; fetch it through the API’s wrapped fields.

Overview

Tools Reference

`register_webhook`

Example response

Event payload

Event types

Verify requests

Handle a notification

​register_webhook

​Example response

​Event payload

​Event types

​Verify requests

​Handle a notification

`register_webhook`

Example response

Event payload

Event types

Verify requests

Handle a notification