Events: how alerts reach you
Every match is written to one running log for your account. Webhooks, email, and MCP reads all draw from it. Your assistant reads from where it left off and never misses an event.
Every result a catch (a standing search) finds is added to one running log for your account, in order, and never changed. That log is the product. Everything else, webhooks included, reads from it.
events
id ev_01J... time-ordered, unique
account_id
catch_id
type result.found | catch.run | delivery.failed | ...
result Result see the API reference
created_atWhy a log
- Your assistant can ask it questions like a database. GET /v1/events?since=<cursor> returns everything after a point. The assistant keeps the cursor, a bookmark of where it stopped. Nothing is lost while it was offline.
- No delivery method is special. A webhook (a web address discatch calls when something happens) is a subscriber that gets called on each new entry. Email is a subscriber that batches. An MCP tool is a subscriber that reads when asked.
- Replaying is free. Change how you handle events and read again from an older bookmark. No "resend" feature needed.
Reading the log
| Method | For | What you get |
|---|---|---|
| GET /v1/events?since=&catch=&type=&limit= | anyone checking on a schedule | a page of events plus next_cursor |
| GET /v1/events?since=&wait=30 | anyone who wants to wait for news | waits up to 30 seconds for a new event |
| GET /v1/events/stream (SSE) | an assistant that is already running | one event per line, and it can resume from Last-Event-ID |
| MCP get_events (planned) | an assistant inside a chat session | the same as the API page |
Filters: catch, type, min_prescore, source, since, until.
Waking up your assistant
"Wake the assistant" means that something able to start an assistant gets called when the log grows. discatch does not run assistants and does not ship a program for your own machine. It calls out, and the thing it calls starts the assistant.
POST /v1/subscriptions
{
"filter": { "catch": "cat_...", "min_prescore": 0.5 },
"target": { "type": "webhook", "url": "https://...", "secret": "whsec_..." }
}| Destination | What discatch does | What starts the assistant |
|---|---|---|
| webhook | sends a signed POST with the batch of events and the bookmark | whatever is behind the address |
| doozy | creates a todo in your Doozy list with the events and a suggested next step | Doozy runs the todo with your assistant, hosted |
| github_dispatch | sends a repository_dispatch to your repo with the batch as the payload | a workflow that runs claude -p or codex exec in CI |
| pane | posts to a RunPane address you set up | Pane Chat picks it up as work |
| email, slack | sends a digest | a person |
What you can count on
- Events never change once written. They are kept for as long as your plan allows: 30 days on the free plan, longer on paid plans.
- Bookmarks (cursors) are stable and never expire while the events exist.
- Webhook delivery is retried on failure, and failed deliveries are kept where you can see them. The payload always carries the bookmark.
- Events are in order within an account.
Webhook payload
{
"event": "catch.fired",
"catch_id": "cat_...",
"delivery_id": "dlv_...",
"fired_at": "RFC 3339",
"results": [ "Result" ],
"suggested_action": "string",
"quote": { "amount_usd": 0.003, "units": { "alert": 1, "result": 3 } }
}Headers: X-Discatch-Signature (a code worked out from the body and your catch secret, so you can check the call really came from discatch), X-Discatch-Delivery, X-Discatch-Attempt. Use delivery_id to spot repeats.
Last reviewed by Parsa Khazaeepoul, founder, dcouple. Copy from docs/onboarding.md, docs/query-language.md, docs/events.md, docs/api.md.