Webhooks
n8n, Slack, Zapier or your own server — registered once, notified with a signature you can verify.
On this page
Add an endpoint
Settings → Webhooks → Add endpoint:
- Name — optional, shown instead of the host.
- URL — http(s); localhost and LAN addresses are fine (n8n, a local relay).
- Events — tick what it should receive.
On save, the signing secret is shown once — copy it then; Magpie cannot show it again. Rotate secret mints a new one and the old one stops working.
Per endpoint: Send test (fires a sample so you can watch it land), Edit, Rotate secret, Pause/Resume, and delete behind a confirm. Secrets live in the OS keyring, or sealed in webhooks.json where no keyring exists — the endpoint’s badge says which.
Events
| Event | Fires when |
|---|---|
watch.changed |
Any watch’s scheduled check finds a change |
crawl.finished |
A crawl ends — finished or stopped |
crawl.failed |
A crawl errors |
An endpoint with no events is still reachable one way: a watch’s Send changes to setting routes that watch’s changes to it alone. That is the scalpel — one endpoint, one page — while the event subscriptions are the broad brush.
Verifying
Deliveries are Standard Webhooks with HMAC-SHA256 signatures. Verify with any Standard Webhooks library using the three headers:
webhook-id— stable per eventwebhook-timestamp— when it was sentwebhook-signature— the HMAC of"{id}.{timestamp}.{body}"with your signing secret
A verified signature means the payload left this machine’s Magpie untouched. The CLI’s magpie watch --webhook is different and lesser on purpose — an unsigned JSON POST for operator-chosen endpoints (CLI reference); the signed registry is the desktop’s.
Deliveries and retries
Deliveries run while Magpie runs. Each endpoint keeps a log of its last 20 attempts — when, which event, the response status, latency, and the error verbatim when there was no response. A failed delivery retries 3 times over about 30 seconds, then waits for the next event.
Pausing an endpoint stops deliveries without deleting it or its secret — the log keeps its history. Watches whose checks fire while the app is closed run at the next launch; for round-the-clock delivery, keep the app in the tray (Background).