Set up your first webhook

This article assumes you already know what webhooks are for. If not, read that first.

Before you start

• You must be a Coordinator of at least one Circle.
• You need a publicly reachable URL that will receive the POSTs. If you are testing, use webhook.site to grab a free temporary URL.
• Your subscription must be active.

Steps

1. Sign in at getwello.co.uk.
2. Open Settings → Developer API.
3. Scroll down to the Webhooks section.
4. In the create form:
   • Name: something you will recognise later, like "Home Assistant kitchen Sonos".
   • Circle: if you Coordinate more than one Circle, pick which one this webhook is for. One subscription per Circle.
   • URL: the URL we should POST to. Must be https:// in production. For local testing, http://localhost is also accepted.
   • Events: tick the ones you want to receive. You can change this later by deleting and re-creating the subscription.
5. Click Create webhook.
6. A modal pops up showing your signing secret, which starts with whsec_. Copy it now. This is the only time it is shown. If you lose it, you delete the subscription and start again.
7. Paste the secret into your integration. How you do this depends on what you are using:
   • Home Assistant: usually in secrets.yaml as getwello_webhook_secret: whsec_....
   • n8n: as a credential, or directly in an HMAC verification node.
   • Custom code: as an env var or constant; never commit it to a public repo.
8. Click I've saved it, close.

Test it works

1. Back on the Developer API page, find your new webhook in the list.
2. Click Test. We fire a synthetic webhook.test event to your URL.
3. A green box appears if your receiver returned a 2xx status. If you see red, the URL is unreachable, the receiver rejected the POST, or returned an error. Check your receiver's logs.

What we send

Every webhook is an HTTPS POST with JSON body. Headers include:

• Content-Type: application/json
• X-Getwello-Event: check_in.created (or whichever event)
• X-Getwello-Timestamp: 1717840923 (Unix seconds at the time we signed)
• X-Getwello-Signature: t=1717840923,v1=8f7d... (HMAC-SHA256 signature)
• X-Getwello-Delivery-Id: a unique id for this specific delivery, useful for deduplication

Body example:

{
  "event": "check_in.created",
  "occurred_at": "2026-06-08T08:14:32Z",
  "circle_id": "9d3...",
  "data": {
    "check_in_id": "5a2...",
    "checkin_member_user_id": "a1b...",
    "status": "well",
    "for_local_date": "2026-06-08"
  }
}

How to verify the signature

This is the bit that proves the request really came from Getwello. Every modern language has an HMAC library; here is the recipe:

1. Read the raw request body as a string. (Do not parse the JSON first; the signature is over the bytes you received.)
2. Read the t value from the signature header.
3. Concatenate: signed_string = t + "." + body
4. Compute HMAC-SHA256 of signed_string using your whsec_ secret as the key.
5. Compare your computed signature (hex) to the v1 value from the header, using a constant-time comparison.
6. Also reject any signature where t is more than 5 minutes old. Stops replay attacks.

In Node.js this looks like:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, body, header) {
  const match = header.match(/^t=(\d+),v1=([a-f0-9]+)$/);
  if (!match) return false;
  const [, t, provided] = match;
  if (Math.abs(Date.now() / 1000 - parseInt(t)) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(`${t}.${body}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

Auto-disable on consecutive failures

If your receiver fails 5 times in a row (any non-2xx response, or no response within 6 seconds), the subscription auto-disables. It stays in your list with an "Auto-disabled" pill. Fix the receiver, then either delete-and-recreate the subscription or contact us.

Worked example

For a real end-to-end recipe wiring Getwello to Home Assistant so the kitchen Sonos announces check-ins, see Sonos announces "Mum has just checked in" via Home Assistant.