What webhooks are, and why you would want one

A webhook is a way for Getwello to tell you when something happens, instead of you asking us over and over.

The shop analogy

Imagine you are waiting for a delivery. There are two ways to know when it arrives:

1. Polling: every two minutes, you open the front door and check. Tiring, and you miss the moment the box actually lands.
2. The doorbell (webhook): the delivery person rings, you get up only when there is something to get up for.

Webhooks are the doorbell. Getwello rings, your house responds.

When you would want a webhook

You would want webhooks if you have something that should react the moment a check-in lands. Examples:

• Your kitchen Sonos announcing "Mum has just checked in" the moment it happens.
• Your Apple Watch buzzing when a check-in is marked missed.
• Your Slack channel mirroring every Family Room message so your siblings (who refuse to download another app) see them.
• Your porch light turning on at 10am if no check-in has come through yet, as a gentle reminder.

If you only ever want to ask the API on demand (like asking Claude "anything from Mum today?"), you do not need webhooks. The MCP server and REST API cover that. Webhooks are specifically for "react instantly to something" use cases.

What events Getwello fires

You pick which of these your webhook receives. You can pick just one, or all of them.

• check_in.created: Mum taps her button. Fires within seconds.
• check_in.missed: the daily cron has marked the check-in as missed once your grace window has passed.
• family_room.message_posted: someone (a human, or an integration tagged "via integration") posts a message in the Family Room thread.
• visit.created: anyone schedules a visit. If a recurrence creates several visits, you get one event per visit.

How a webhook works

1. You tell Getwello: "here is a URL you control, please POST to it when these events happen."
2. Getwello generates a signing secret and shows it to you once. You save the secret.
3. When a matching event happens, Getwello sends an HTTPS POST to your URL with the event details as JSON.
4. Each POST includes a signature header so your receiver can verify the request really came from Getwello and not someone faking it.
5. Your integration (Home Assistant, n8n, a small script, whatever) reads the JSON and reacts however you have programmed it to. Light goes on, speaker announces, Slack pings, whatever.

What you need to set one up

• A publicly reachable URL. "Publicly reachable" means our servers can send a POST to it. If your URL is http://192.168.1.45/webhook (a local IP), we cannot reach it. Solutions: Home Assistant Cloud, ngrok, Cloudflare Tunnel, n8n's hosted version, or a small Cloudflare Worker as a relay.
• An integration that can receive POSTs (any modern automation tool can).
• An API key (see Create your first API key).

If you have all that, see Set up your first webhook.

What if my receiver is down when an event fires?

For v1, the event is logged as a delivery failure and we move on. If your receiver fails 5 times in a row, the subscription auto-disables and waits for you to come back to settings, so a dead URL does not keep ringing forever. Full retry queues with exponential backoff are on the roadmap.

How is this different from the MCP server?

Use case	Best tool
Ask Claude "how is Mum's week going?"	MCP server
Smart speaker announces check-in the moment it happens	Webhook
Generate a daily summary every Sunday evening	Either, but REST API is simpler
Read by hand from a Python script	REST API

They all live alongside each other. Use whichever fits the moment.