Webhooks

Setting one up

1. In Gairė, open Recipients and choose Webhook. Give it a name and paste an address that starts with https://.
2. Gairė shows the webhook's secret once, as soon as it is added. Keep it if you want to check that a request came from Gairė.
3. Gairė sends a six-digit code to that address straight away. Type it into Gairė within 10 minutes.
4. A watch tells all your recipients, unless you chose some for it. If you did, make sure the webhook is one of them.

What is sent

One POST with a JSON body. For a change:

{
  "event": "detection",
  "host": "shop.lt",
  "headline": "price drop on shop.lt",
  "summary": "Sony 89 € → 61 €",
  "url": "https://gaire.lt/c/…",
  "id": "48213",
  "detected_at": "2026-10-19T06:00:00.000Z",
  "watch": { "id": "…", "name": "Televisions", "url": "https://shop.lt/tv" },
  "changes": [
    {
      "type": "price",
      "name": "Sony",
      "previous_name": "Sony",
      "url": "https://shop.lt/tv/sony-1",
      "price": "61 €",
      "price_value": 61,
      "previous_price": "89 €",
      "previous_price_value": 89,
      "in_stock": null,
      "previous_in_stock": null
    }
  ]
}

• event: what happened. detection is a change on a watched page.
• host: the watched site.
• headline: a one-line title, the same as an email's subject, in your account's language.
• summary: the change in one sentence, in your account's language.
• url: the change's page on Gairė.

Then each change as separate fields, in English whatever your account's language:

• id: the change's own id. A request sent again after a failure has the same one.
• detected_at: when Gairė found it, in UTC.
• watch: the watch's id, its name and the watched page's address.
• changes: every thing that changed. type is new, price, availability, details (its name or details), page_text (a watched part of a page) or page_text_gone. Each has its name and its previous name, its own address on the site when it has one, the price and the previous price as Gairė shows them and as numbers, and whether it is in stock now and was before. A value the page does not give is null.

The code from step 3 comes as {"event": "verify", "message": "…"}. Other events may come, such as digest; ignore what you don't use.

Checking it came from Gairė

Each request carries two headers:

• X-Gaire-Timestamp: the time it was sent, in Unix seconds.
• X-Gaire-Signature: sha256= followed by an HMAC-SHA256, in hex, made with your secret over the timestamp, a full stop, and the body exactly as received.

const crypto = require("node:crypto");

function fromGaire(secret, timestamp, rawBody, signature) {
  if (typeof signature !== "string") return false;
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Sign the body you received, not a copy rebuilt from parsed JSON: a change in spacing or key order breaks the match.

Delivery

• Answer with any 2xx within 5 seconds. Gairė does not read what you answer.
• No answer, or a 5xx: Gairė tries again after 1, 5 and 25 minutes.
• A 4xx, or a redirect: not tried again, and a redirect is not followed. Some addresses answer with a redirect, Google Apps Script's among them, and do not work here directly.
• Only https://, and only addresses on the public internet.

Limits

A webhook is one of your 5 recipients. On the free plan, up to 300 webhook alerts a month are sent, counted apart from email.