Real-time material-event alerts
Create a monitor and a signed webhook, and get pushed the moment a matching SEC filing or event lands — no polling.
Real-time material-event alerts
Stop polling. Create a monitor on a company or form type, attach a webhook endpoint, and Clous POSTs you a signed event the moment a matching filing is detected.
Prerequisites
- A Clous API key — get one free.
export CLOUS_API_KEY=clous_live_... - An HTTPS endpoint that can receive a POST.
1. Register a webhook endpoint
POST /v1/webhooks/endpointscurl -s -X POST "https://api.clous.ai/v1/webhooks/endpoints" \
-H "Authorization: Bearer $CLOUS_API_KEY" -H "Content-Type: application/json" \
-d '{ "url": "https://api.acme.com/webhooks/clous", "description": "prod" }'The response includes a secret — store it, it signs every delivery.
2. Create a monitor
Watch NVIDIA for material changes, firing the webhook on each match:
curl -s -X POST "https://api.clous.ai/v1/monitors" \
-H "Authorization: Bearer $CLOUS_API_KEY" -H "Content-Type: application/json" \
-d '{
"name": "NVIDIA material changes",
"target_type": "ticker", "target_value": "NVDA",
"signals": ["sec.filing.new", "sec.8k.executive_change", "sec.form4.insider_sell"],
"materiality": "medium",
"webhook_endpoint_id": "<endpoint id from step 1>"
}'Or watch every new 8-K market-wide: target_type: "form", target_value: "8-K",
empty signals.
3. Receive and verify the webhook
Each delivery is signed: Clous-Signature: sha256=HMAC(secret, "{timestamp}.{body}").
Verify before trusting it:
import hmac, hashlib
def verify(secret, headers, raw_body: bytes) -> bool:
ts = headers["Clous-Timestamp"]
expected = "sha256=" + hmac.new(
secret.encode(), f"{ts}.{raw_body.decode()}".encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, headers["Clous-Signature"])The body carries the full event:
{ "type": "sec.filing.new", "monitor_id": "…", "delivery_id": "…",
"event": { "event_type": "sec.filing.new", "importance": "medium",
"entity_name": "NVIDIA Corp", "entity_cik": "0001045810",
"summary": "…", "evidence": [ … ] } }4. Check the delivery log
curl -s "https://api.clous.ai/v1/webhooks/deliveries" \
-H "Authorization: Bearer $CLOUS_API_KEY"Failed deliveries retry with backoff (1m → 5m → 30m → 2h).
How it works
A background evaluator turns EDGAR filings into typed events,
matches them to your active monitors, and delivers a signed
webhook per match. Pause a monitor any time with
PATCH /v1/monitors/{id} {"status":"paused"}.