App webhooks
One delivery URL and signing secret per app; how Smileline materialises a verified endpoint for every connected practice and what it sends.
An app can register one delivery URL, one signing secret and a list of events. For every practice that connects, Smileline creates a webhook endpoint in that practice pointing at your URL, verifies it, and delivers that practice's events to it. You do not subscribe per practice.
Payloads, headers and the signature are the same as the practice-managed outbound webhooks described on the Webhooks page.
Set it up
On the app's Webhooks tab, enter the HTTPS delivery URL and tick the events. Save. The signing secret is created with the first save and shown once.
Make your endpoint answer the verification challenge: Smileline sends a request carrying an X-Hook-Secret header, and your endpoint must reply 2xx with the same header and value. Verification is retried with backoff (one minute up to daily) until it succeeds, so a fix on your side is picked up without any action in the portal.
Verify X-SmileLine-Signature on every delivery with the app's signing secret exactly as shown under Verify the signature.
When endpoints appear
Within about five minutes of a practice connecting, its endpoint is created and challenged. Delivery starts after the first successful echo. Events that happen in between are not queued for that endpoint; if your app needs them, backfill from the list endpoints, which carry created and updated timestamps.
Each practice receives only the events its own consent admits: an event's area must be among the granted scopes (see Scopes). Adding events to the app later never widens a practice's existing grant; a practice whose grant admits none of the app's events gets no endpoint until one of them is admitted.
One endpoint per practice
A practice has one endpoint for your app however many of its staff authorised it. The endpoint carries the oldest live authorisation's grant. When that authorisation is revoked, the endpoint is archived, in-flight deliveries are ended, and the next reconciliation recreates it under the next authorisation with its own grant.
Practices see the endpoint under Settings → Integrations → Outbound webhooks, read-only. Disconnecting the app is their remedy; it archives the endpoint at once.
Limits and rotation
- A practice can hold at most 20 live endpoints across every app and its own. If a practice is at that limit, your endpoint is not created; the practice sees an audit entry and Smileline retries when capacity frees.
- Regenerating the signing secret replaces every practice's endpoint with a freshly verified one under the new secret. Update your verifier first.
- Changing the delivery URL does the same: new endpoints are created and verified, old ones archived.
Practice-managed subscriptions still work
A connection can also call
POST /settings/webhook-endpoints/subscriptions with its own URL and receive
a per-practice secret, exactly as the Zapier app does. Use that when a
practice must choose its own destination.