Phone system webhook
Connect a phone system Smileline has no direct connection to by sending each ringing and finished call to a signed webhook.
Use this when your practice's phone system isn't one Smileline connects to directly — a reseller's platform or a system you host yourself — but it (or whoever runs it for you) can send an HTTPS request when a call rings and when it ends. Each finished call then lands in the call log and on the patient's timeline, its recording is copied into Smileline, and missed calls are followed up, as described in Phone providers.
Calls you make stay in your own phone system: Smileline can't dial through it.
Set it up
Open Settings → Phone providers and, on the Other phone system (webhook) card, click Connect. Only the practice owner can do this.
Copy the Webhook URL and the Signing secret into your phone system, then click Done. Both are shown once: Smileline cannot show them again.
Make a test call and check it appears in the call log. Smileline answers
200 even to a URL it doesn't recognise, so a mistyped URL fails quietly.
If you lose the URL or the secret, click New URL and secret on the card. Every pair you replace keeps working for 24 hours from when you replaced it — even if you make another new pair meanwhile — so you have time to update your phone system. You can make a new pair up to ten times in 24 hours.
Sign each request
Send every request as POST with Content-Type: application/json and a JSON
body of up to 256 KiB, and add two headers:
| Header | Value |
|---|---|
X-SmileLine-Timestamp | The current Unix time in seconds. |
X-SmileLine-Signature | v1= followed by the hexadecimal HMAC-SHA256 digest of the signed bytes, using the signing secret as the key. |
The signed bytes are the timestamp, a full stop, then the exact raw request body:
timestamp.rawBodySign the exact bytes you send: reformatting the JSON or adding a newline after signing makes the signature invalid. Sign each attempt as you send it — a timestamp more than five minutes away from when Smileline receives the request is refused as a possible replay.
Smileline checks the signature the moment the request arrives, so a request it has already kept is never affected by a new pair made after it. A request whose signature doesn't verify, or whose timestamp is too old, is still kept: it goes to the review queue instead of the call log.
A ringing call
Optional. Send it as the phone starts ringing, and Smileline looks the caller up — or creates the lead when nobody matches, as for a website enquiry.
{
"type": "ring",
"callId": "call-8812",
"from": "+447700900123",
"to": "+442079460123",
"at": "2026-11-14T10:15:02Z"
}| Field | Required | Meaning |
|---|---|---|
type | Yes | ring |
callId | Yes | Your system's ID for the call, up to 200 characters. Use the same ID for the call's ring and its finished call. |
from | Yes | The caller's number, in international format (+44…). |
to | Yes | Your practice number they called. |
at | Yes | When it started ringing. |
A finished call
Send it once the call has ended — within 48 hours of the call starting. What counts is when Smileline received it, not when it got round to processing it.
{
"type": "completed",
"callId": "call-8812",
"sentAt": "2026-11-14T10:21:40Z",
"direction": "inbound",
"from": "+447700900123",
"to": "+442079460123",
"startedAt": "2026-11-14T10:15:02Z",
"answeredAt": "2026-11-14T10:15:09Z",
"endedAt": "2026-11-14T10:21:31Z",
"agentEmail": "reception@example.com",
"voicemail": false,
"recordingUrl": "https://recordings.example.com/call-8812.mp3",
"summary": "Asked about whitening; booked a consultation."
}| Field | Required | Meaning |
|---|---|---|
type | Yes | completed |
callId | Yes | Your system's ID for the call, up to 200 characters. |
sentAt | Yes | When you sent this version of the call. When you send a call more than once, the latest sentAt wins. |
direction | Yes | inbound or outbound. |
from | Yes | Who rang: the caller for an inbound call, your practice number for an outbound one. |
to | Yes | Who was rung. |
startedAt | Yes | When the call started ringing. |
answeredAt | No | When someone answered. Leave it out, or send null, for a call nobody answered. |
endedAt | Yes | When the call ended. |
agentEmail | No | The email of the person who answered (inbound) or dialled (outbound). |
voicemail | No | true when the caller left a voicemail. |
recordingUrl | No | An https link to the call's recording. See Recordings. |
summary | No | Your system's own summary of the call. |
Times are ISO 8601 with a time zone, such as 2026-11-14T10:15:02Z, and must
run in order: startedAt, then answeredAt, then endedAt. A call longer than
eight hours goes to the review queue. A body that is not one of these two
shapes is kept in the review queue, never dropped.
Worked example
With the URL and secret in SMILELINE_WEBHOOK_URL and
SMILELINE_WEBHOOK_SECRET, from a shell:
body='{"type":"ring","callId":"call-8812","from":"+447700900123","to":"+442079460123","at":"2026-11-14T10:15:02Z"}'
timestamp="$(date +%s)"
signature="$(printf '%s' "${timestamp}.${body}" | openssl dgst -sha256 -hmac "$SMILELINE_WEBHOOK_SECRET" -hex | sed 's/^.* //')"
curl -X POST "$SMILELINE_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "X-SmileLine-Timestamp: ${timestamp}" \
-H "X-SmileLine-Signature: v1=${signature}" \
--data-binary "$body"The same in Node.js:
import { createHmac } from "node:crypto";
export async function sendToSmileline(call) {
const body = JSON.stringify(call);
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = createHmac("sha256", process.env.SMILELINE_WEBHOOK_SECRET)
.update(`${timestamp}.${body}`)
.digest("hex");
const response = await fetch(process.env.SMILELINE_WEBHOOK_URL, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-SmileLine-Timestamp": timestamp,
"X-SmileLine-Signature": `v1=${signature}`,
},
body,
});
// Anything but 200 means Smileline did not keep it: send it again later.
if (response.status !== 200) {
throw new Error(`Smileline answered ${response.status}`);
}
}Retries and corrections
Smileline stores each request before it reads it and answers in milliseconds:
200— kept. Smileline processes it a moment later.503— not kept. Send it again after theRetry-Afterseconds.429— too many requests from your address. Send it again after theRetry-Afterseconds.413— the body is larger than 256 KiB.
Sending the same body again is safe: a copy of a request Smileline already
has changes nothing. To correct a finished call — a recording that became
available later, a fixed summary — send the whole completed body again
with a later sentAt. The call is updated in place. A body whose sentAt is
not later than the one Smileline holds for that call changes nothing, so
corrections that arrive out of order never undo a newer one — including ones
you replay from the review queue. Smileline takes up to three corrections per
call on its own; a further one waits in the review queue with Try again.
Once your practice's retention window for the call's transcript has passed,
Smileline no longer accepts corrections to that call.
Recordings
Smileline copies the file at recordingUrl once into its own storage and
plays and transcribes it from there. The link must:
- be
httpson a public address, needing no login or extra headers; - serve the audio file itself (at most three redirects), up to 32 MiB;
- stay fetchable for 7 days after you send it.
If the link has expired or the file can't be fetched, Smileline tries again a
few times, each time with the newest finished call you sent — so sending the
call again with a later sentAt and a fresh recordingUrl replaces the link.
If every try fails, the call stays in the call log and the recording shows in
the review queue with Retry.
Who took the call
Smileline matches agentEmail to the member of your practice with the same
email address, checking again on every call: a member whose access is
suspended, or who has left, is no longer credited. Each address appears
under People on the card the first time it is sent; if someone uses a
different address in your phone system, choose them there — a choice you
make by hand always wins. A call with no match is logged without a person.
Pause, disconnect and review
The card's dropdown pauses or disconnects the webhook as for any phone provider. Anything Smileline couldn't process is listed in the review queue, with View details, Try again where it can help, Mark as handled and Delete.
Phone providers
Keep the phone system your practice already uses — JustCall, Aircall or VoiceStack — and still get calls on the patient's timeline, callers recognised while the phone rings and calls dialled from Smileline.
Notifications
The bell tells you what happened while you were looking somewhere else — and nags when a new lead still hasn't been called.