matchstick

Matchstick for agents

Version 1.5.0 · All sections

Updates and webhooks: noticing new work

Matchstick's tools answer questions; these two paths tell a client that something happened. Both read the same feed, so a poller and a webhook never disagree about what counts: a weekly report finished, a finding became open or open again, a change became ready for review. Daily crawl noise and findings Matchstick handles on its own don't count.

Polling: get_updates_since

Free. Pass since as an ISO 8601 moment or the next_cursor of your previous call (default: the last 24 hours), and a site or none for every site the credential sees. The answer carries reports, findings and changes oldest first, each site's last_report and open_findings by doer (you, matchstick, matchstick_with_approval), server_time and next_cursor. Nothing happened: changed: false and empty lists. The window ends a few seconds behind the clock so a row still committing is never skipped; more: true means the window was cut at the last item and the next call continues from the cursor.

GET https://matchstick.io/api/v1/updates?site=example.com&since=2026-10-25T13:00:00Z

Every site-scoped read also carries last_report_at, last_report_id, last_report_url and open_findings_count (list_sites, list_findings, get_report, the REST mirrors), so a client can tell "a report just finished" from "the same stale items" without a second call.

Webhooks

A person adds a URL on Settings → Webhooks and picks the events. Matchstick POSTs one JSON message per event within about half a minute, oldest first, and signs each one.

EventFires whendata
report.finishedA weekly report finished.report (id, finished_at, overall_status, headline, summary, findings_opened, url), open_findings (total, by_doer), open_changes.
finding.openedA finding whose doer is you or matchstick_with_approval became open or open again and is still open.finding (id, title, why, kind, doer, confidence, urls, status, reopened, report_id, url).
change.ready_for_reviewA pull request Matchstick drafted, revised or rebased is open for review.change (id, title, status, number, risk, url, pr_url).

Headers: X-Matchstick-Event, X-Matchstick-Delivery (the event id, repeated on a retry so a receiver can drop a duplicate), X-Matchstick-Signature: t=<unix seconds>,v1=<hex> where v1 is the HMAC-SHA256 of <t>.<raw body> with the webhook's secret (shown once when it is made; reject a t older than 5 minutes). Answer 2xx within 10 seconds. A failure is retried with a growing wait (1, 2, 4 … 60 minutes) and later events wait behind it, in order; after 20 failures in a row the webhook pauses until a person resumes it. A test delivery (type: "ping", no site) is available from the same page.

{
  "id": "evt_3f9c2a7d1e8b4c6a9d0f1e2b",
  "type": "finding.opened",
  "at": "2026-10-26T13:04:11.512Z",
  "site": {
    "id": "<site id>",
    "domain": "example.com",
    "url": "https://matchstick.io/sites/<site id>"
  },
  "data": {
    "finding": {
      "id": "<finding id>",
      "title": "Request indexing for /about",
      "why": "Google hasn't indexed a page that ranks for its name.",
      "kind": "indexing",
      "doer": "you",
      "confidence": "high",
      "urls": [
        "/about"
      ],
      "status": "open",
      "reopened": false,
      "report_id": "<report id>",
      "url": "https://matchstick.io/reports/<report id>"
    }
  }
}