Management API
Base URL https://api.samhooks.com. Auth: Authorization: Bearer <token> on every route except demo feeds, /status.json, RSS capability URLs, and token recovery.
The matching contract (binding)
A filter is {"naics": [...], "set_asides": [...], "keywords": [...]}. Each list may be empty; at least one must be non-empty (else HTTP 400). An empty list is a wildcard for that dimension.
- AND across dimensions, OR within a list: a change matches iff every non-empty list matches; a list matches if any entry matches.
- NAICS (max 20 entries): digit strings of length 2–6. 6 digits = exact; fewer = prefix (
"5415"matches 541511). - Set-asides (max 20): case-insensitive exact match on the extract's code (e.g.
SBA,8A). - Keywords (max 5, each 2–64 chars): case-insensitive substring match after Unicode NFKC normalization of both sides, against the title and description. No stemming, no regex, no phrase quoting.
- Matching is evaluated per change at enqueue time; editing a filter affects future changes only. No retro-matching, no backfill.
Routes
| Route | What it does |
|---|---|
POST /v1/filters | Create (10-filter cap → HTTP 402). Returns the filter + RSS capability URL (once). |
GET /v1/filters, GET /v1/filters/:id | List / fetch. |
PUT /v1/filters/:id | Update. Any successful PUT resets the consecutive-failure counter and re-enables a disabled endpoint. |
DELETE /v1/filters/:id | Delete filter and its feed. |
POST /v1/test-delivery | Fires a sample signed payload at your webhook URL; returns its status code. Works while disabled. |
GET /v1/status | Your last 100 delivery attempts + endpoint states. |
POST /v1/token/rotate | New token (shown once); old token dies immediately. |
POST /v1/token/recover | Lost-token reissue — see below. |
Lost your token?
POST /v1/token/recover with {"invoice_id": "in_...", "email": "you@example.com"}. The invoice ID is on every Stripe receipt email and in the Stripe customer portal. If the invoice belongs to your active subscription and the email matches, you get a fresh token (shown once; the old one is invalidated). Any mismatch returns a uniform 404. Limited to 5 attempts/hour/IP.
Cancellation
Manage or cancel via the Stripe customer portal link on your receipt. On cancellation your token, webhooks, and feeds stop at the end of the billing period.