Webhooks

Get notified the moment something changes.

Add a webhook to any source and TrackChanges sends a POST request there automatically whenever a new version is detected, no polling on your end required.

Adding a webhook

$ tch poll add-webhook stripe-api https://hooks.slack.com/services/...

Any URL works: Slack, PagerDuty, a custom endpoint, or a tool like webhook.site for testing.

Payload shape

Sent as a standard JSON POST body:

{
  "event":       "version.changed",
  "source_uuid": "6dbae3be-63e7-40c4-9223-7af5e1369946",
  "diff_id":     "a13df8e1-...-e771fc2d374",
  "severity":    "breaking",
  "reasons":     ["removed 1 endpoint(s)"],
  "summary":     {"added": 0, "removed": 1, "changed": 0},
  "text":        "[trackchanges] stripe-api — breaking change detected: removed 1 endpoint(s)"
}

event	string	Always `version.changed` for a real delivery
source_uuid	uuid	Which source changed
diff_id	uuid	Fetch the full diff via `GET /diffs/{diff_id}`
severity	string	`breaking` or `nonbreaking`
reasons	string[]	Human-readable explanation of the classification
summary	object	Counts of added / removed / changed elements
text	string	One-line rendering, present so Slack and similar tools display something readable automatically

Slack compatible out of the box. Slack's incoming webhooks only render a text field, so every payload includes one. Paste a Slack webhook URL in directly, no extra formatting needed.

Testing a webhook

Fire a synthetic payload without waiting for a real change:

$ tch poll test-webhook stripe-api
stripe-api: fired → https://hooks.slack.com/services/... (slack)

Test payloads use "event": "version.changed.test" and "severity": "test" so your receiving end can distinguish them from real changes if needed.

Fetching the full diff

The webhook payload includes counts and reasons, but not the raw diff. Pull that separately using diff_id:

# get the full diff behind a webhook delivery
curl https://api.trackchanges.io/diffs/{diff_id} \
  -H "Authorization: Bearer $API_KEY"

Managing webhooks

$ tch poll list-webhooks stripe-api
$ tch poll remove-webhook stripe-api <id|alias>