feat(webhooks): remove subject-based subscription surface (v0.7.0)

Folds in the work from PR #27 (issue-2275-drop-subjects) plus three
cleanup-batch carry-overs from tango's `dogpile/api-cleanup-batch`:

- #2256: add `endpoint` kwarg to create_webhook_alert (multi-endpoint
  accounts can now use the convenience wrapper)
- #2254: remove `ordering` kwarg from list_notices and list_protests
  (server rejects every value)
- #2252: switch test_webhook_delivery to canonical `endpoint` body key

Closes makegov/tango#2275 — part of makegov/tango#2267.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: infinityplusone

CHANGELOG.md

@@ -7,13 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+> Combined release: API parity (formerly tracked as PR #25) + subject-based
+> webhook removal (formerly tracked as PR #27 / issue #2275). Bumped to
+> `0.7.0` because removing `create_webhook_subscription` /
+> `update_webhook_subscription` / `delete_webhook_subscription` /
+> `list_webhook_subscriptions` / `get_webhook_subscription` and the
+> `WebhookSubscription` + `WebhookSubjectTypeDefinition` dataclasses is a
+> breaking change.
+
 ### Added
-- `ordering` parameter on `list_forecasts`, `list_grants`, `list_subawards`, `list_gsa_elibrary_contracts`, `list_opportunities`, `list_notices`, and `list_protests`. Prefix with `-` for descending. Closes a parity gap with the API surface (these endpoints all accept `?ordering=` server-side).
+- `ordering` parameter on `list_forecasts`, `list_grants`, `list_subawards`, `list_gsa_elibrary_contracts`, and `list_opportunities`. Prefix with `-` for descending. Closes a parity gap with the API surface (these endpoints all accept `?ordering=` server-side).
 - `create_webhook_endpoint` accepts `name=` (keyword-only). Required by the Tango API since multi-endpoint support landed; omitting it now emits a `DeprecationWarning` and will become an error in a future major version.
-- `create_webhook_subscription` accepts `endpoint=`, `subscription_type=`, `query_type=`, `filter_definition=`, `frequency=`, `cron_expression=`, `is_active=` (keyword-only). Lets callers target a specific endpoint and create filter subscriptions through the canonical API.
-- `update_webhook_subscription` accepts `frequency=`, `cron_expression=`, `is_active=` for filter-subscription updates.
 - `update_webhook_endpoint` accepts `name=` for renaming an endpoint.
-- Webhook alerts (filter subscriptions): `list_webhook_alerts`, `get_webhook_alert`, `create_webhook_alert`, `update_webhook_alert`, `delete_webhook_alert` — the convenience layer over `/api/webhooks/alerts/`. New `WebhookAlert` dataclass exported from the top-level package.
+- Webhook alerts (filter subscriptions): `list_webhook_alerts`, `get_webhook_alert`, `create_webhook_alert`, `update_webhook_alert`, `delete_webhook_alert` — the canonical write surface over `/api/webhooks/alerts/`. New `WebhookAlert` dataclass exported from the top-level package.
 - `resolve(name, target_type, ...)` — POST `/api/resolve/` to rank entity / organization candidates from a free-text name. Returns `ResolveResult` with `ResolveCandidate` entries (both exported).
 - `validate(identifier_type, value)` — POST `/api/validate/` to validate the format of a PIID, solicitation number, or UEI. Returns `ValidateResult` (exported).
 - Reference data: `list_departments`, `get_department`, `list_psc`, `get_psc`, `get_psc_metrics`, `get_naics`, `get_naics_metrics`, `get_business_type`, `list_assistance_listings`, `get_assistance_listing`, `list_mas_sins`, `get_mas_sin`.
@@ -22,6 +28,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Agency sub-resources: `list_agency_awarding_contracts`, `list_agency_funding_contracts`.
 - Misc: `search_opportunity_attachments(q, top_k, include_extracted_text)` for `/api/opportunities/attachment-search/`; `get_version()` for `/api/version/`; `list_api_keys()` for `/api/api-keys/`.
 
+### Changed
+- `create_webhook_alert` accepts `endpoint=` (keyword-only). Required for accounts with multiple webhook endpoints; auto-resolves for single-endpoint accounts. Closes the multi-endpoint smoke-test gap (tango#2256).
+- `test_webhook_delivery` now sends the canonical `endpoint` body key instead of the deprecated `endpoint_id` alias (tango#2252). The Python kwarg name stays `endpoint_id=` for backwards compatibility; the wire payload is what changed.
+
+### Removed
+- **Subject-based webhook subscription surface** (tango#2275). Migrate to `create_webhook_alert(...)` and the alerts API.
+  - Methods: `list_webhook_subscriptions`, `get_webhook_subscription`, `create_webhook_subscription`, `update_webhook_subscription`, `delete_webhook_subscription`.
+  - Dataclasses: `WebhookSubscription`, `WebhookSubjectTypeDefinition`. Both are no longer exported from the top-level `tango` package — importing them raises `ImportError`.
+  - Fields: `default_subject_type` removed from `WebhookEventType`; `subject_types` and `subject_type_definitions` removed from `WebhookEventTypesResponse`. The server's `/api/webhooks/event-types/` response no longer carries these.
+  - CLI: the entire `tango webhooks subscriptions` Click subgroup (`list` / `get` / `create` / `delete`). Use the SDK's `client.create_webhook_alert(...)` etc. directly — there is no CLI subgroup for alerts.
+- `ordering` kwarg from `list_notices` and `list_protests`. The notices and protests viewsets reject every `?ordering=` value at runtime (tango#2254); the kwarg silently sent unsupported values. Other five list methods retain `ordering`.
+
 ### Fixed
 - `TangoClient._post()` and `_patch()` now accept both `json_data=` (positional) and `json=` (keyword) for backward compatibility. Internal callers and docs examples that use `json=` no longer fail with `TypeError`.
 

README.md

@@ -384,9 +384,8 @@ tango webhooks simulate --secret $SECRET --event-type entities.updated  # sign +
 tango webhooks simulate --secret $SECRET --event-type entities.updated \
     --to http://127.0.0.1:8011/tango/webhooks         # also POST
 
-# Manage real subscriptions and endpoints
-tango webhooks endpoints     create|list|get|delete
-tango webhooks subscriptions create|list|get|delete
+# Manage delivery endpoints
+tango webhooks endpoints create|list|get|delete
 
 # Force a real test delivery from Tango
 tango webhooks trigger

docs/API_REFERENCE.md

@@ -1554,7 +1554,7 @@ results = client.search_opportunity_attachments(
 
 ## Webhook Alerts
 
-The Alerts API is a filter-subscription convenience layer on top of subscriptions.
+The Alerts API is the canonical (and only) write surface for webhook subscriptions. Every alert maps to one of the five `alerts.*.match` event types and delivers when its saved-search filters match new or modified records.
 
 ### list_webhook_alerts()
 
@@ -1578,9 +1578,20 @@ alert = client.create_webhook_alert(
 )
 ```
 
+For multi-endpoint accounts, pin the delivery target with `endpoint=`:
+
+```python
+alert = client.create_webhook_alert(
+    name="New cloud IT contracts",
+    query_type="contract",
+    filters={"naics": "541511"},
+    endpoint="ENDPOINT_UUID",
+)
+```
+
 **Notes:**
 - `name` and `query_type` are required. `query_type` is **singular** (e.g. `"contract"`, not `"contracts"`).
-- Field naming differs from `create_webhook_subscription`: `name` / `filters` here vs `subscription_name` / `filter_definition`.
+- `endpoint=` is optional and only required when the account has multiple webhook endpoints; for single-endpoint accounts the server auto-resolves.
 
 ### update_webhook_alert()
 
@@ -1614,67 +1625,19 @@ keys = client.list_api_keys()
 
 ## Webhooks
 
-Webhook APIs let **Large / Enterprise** users manage subscription filters for outbound Tango webhooks.
+Webhook APIs let **Large / Enterprise** users manage delivery endpoints and discover the supported event-type catalog. Filter subscriptions (alerts) live in the [Webhook Alerts](#webhook-alerts) section above.
 
 > **For testing, signing, and a CLI tool**, see [`docs/WEBHOOKS.md`](WEBHOOKS.md). This section covers SDK method signatures only.
 
 ### list_webhook_event_types()
 
-Discover supported `event_type` values and subject types.
+Discover supported `event_type` values.
 
 ```python
 info = client.list_webhook_event_types()
 print(info.event_types[0].event_type)
 ```
 
-### list_webhook_subscriptions()
-
-```python
-subs = client.list_webhook_subscriptions(page=1, page_size=25)
-```
-
-Notes:
-
-- This endpoint uses `page` + `page_size` (tier-capped) rather than `limit`.
-
-### get_webhook_subscription()
-
-```python
-sub = client.get_webhook_subscription("SUBSCRIPTION_UUID")
-```
-
-### create_webhook_subscription()
-
-```python
-sub = client.create_webhook_subscription(
-    "Track specific vendors",
-    {
-        "records": [
-            {"event_type": "awards.new_award", "subject_type": "entity", "subject_ids": ["UEI123ABC"]},
-            {"event_type": "awards.new_transaction", "subject_type": "entity", "subject_ids": ["UEI123ABC"]},
-        ]
-    },
-)
-```
-
-Notes:
-
-- Prefer v2 fields: `subject_type` + `subject_ids`.
-- Legacy compatibility: `resource_ids` is accepted as an alias for `subject_ids` (don’t send both).
-- Catch-all: `subject_ids: []` means “all subjects” for that record and is **Enterprise-only**. Large tier users must list specific IDs.
-
-### update_webhook_subscription()
-
-```python
-sub = client.update_webhook_subscription("SUBSCRIPTION_UUID", subscription_name="Updated name")
-```
-
-### delete_webhook_subscription()
-
-```python
-client.delete_webhook_subscription("SUBSCRIPTION_UUID")
-```
-
 ### list_webhook_endpoints()
 
 List your webhook endpoint(s).
@@ -1710,10 +1673,10 @@ print(result.success, result.status_code)
 
 ### get_webhook_sample_payload()
 
-Fetch Tango-shaped sample deliveries (and sample subscription request bodies).
+Fetch Tango-shaped sample deliveries.
 
 ```python
-sample = client.get_webhook_sample_payload(event_type="awards.new_award")
+sample = client.get_webhook_sample_payload(event_type="alerts.contract.match")
 print(sample["event_type"])
 ```
 
@@ -1722,7 +1685,7 @@ print(sample["event_type"])
 The API does not currently expose a public `/api/webhooks/deliveries/` or redelivery endpoint. Use:
 
 - `test_webhook_delivery()` for connectivity checks
-- `get_webhook_sample_payload()` for building handlers + subscription payloads
+- `get_webhook_sample_payload()` for building handlers
 
 ### Receiving webhooks (signature verification)
 

docs/WEBHOOKS.md

@@ -1,6 +1,6 @@
 # Webhooks Guide
 
-This guide covers everything `tango-python` provides for **building, testing, and operating webhook integrations against the Tango API**: signing helpers, a local receiver, a command-line tool, and management commands for the underlying endpoints and subscriptions.
+This guide covers everything `tango-python` provides for **building, testing, and operating webhook integrations against the Tango API**: signing helpers, a local receiver, a command-line tool, and management commands for the underlying endpoints and alerts.
 
 If you only need the SDK method signatures, see [`API_REFERENCE.md` § Webhooks](API_REFERENCE.md#webhooks). For the API-level contract (signing scheme, event taxonomy, retry behavior), see the [Tango Webhooks Partner Guide](https://docs.makegov.com/webhooks-user-guide/).
 
@@ -18,7 +18,6 @@ If you only need the SDK method signatures, see [`API_REFERENCE.md` § Webhooks]
   - [`tango webhooks fetch-sample`](#tango-webhooks-fetch-sample)
   - [`tango webhooks list-event-types`](#tango-webhooks-list-event-types)
   - [`tango webhooks endpoints`](#tango-webhooks-endpoints)
-  - [`tango webhooks subscriptions`](#tango-webhooks-subscriptions)
 - [Programmatic use](#programmatic-use)
   - [Signature verification in your handler](#signature-verification-in-your-handler)
   - [`WebhookReceiver` in pytest fixtures](#webhookreceiver-in-pytest-fixtures)
@@ -54,18 +53,18 @@ tango webhooks --help
 
 ## Concepts in 60 seconds
 
-Tango webhooks have three pieces of state:
+Tango webhooks have two pieces of state:
 
 | Concept | What it is | Tango term |
 |---|---|---|
 | **Endpoint** | The URL Tango POSTs to, plus a generated signing secret | `WebhookEndpoint` |
-| **Subscription** | A filter saying *which events* you want delivered to that endpoint | `WebhookSubscription` |
+| **Alert** | A saved-search filter saying *which matches* to deliver | `WebhookAlert` (filter subscription) |
 | **Delivery** | A single signed POST Tango makes when a matching event fires | (the request itself) |
 
 A typical setup:
 
 1. **Create an endpoint** (`POST /api/webhooks/endpoints/`) with the public URL of your handler. Tango returns a `secret` — save it; it's used to sign every delivery.
-2. **Create one or more subscriptions** (`POST /api/webhooks/subscriptions/`) describing the events your handler cares about (e.g. `entities.updated` for specific UEIs).
+2. **Create one or more alerts** (`POST /api/webhooks/alerts/`) describing the saved-search matches you want delivered (e.g. opportunities matching `naics=541511`). Each alert maps to one of five `alerts.*.match` event types.
 3. **Tango POSTs** to your endpoint when matching events fire. The body is JSON; the header `X-Tango-Signature: sha256=<hex>` is the HMAC-SHA256 of the raw body bytes keyed by your endpoint's secret.
 4. **Your handler verifies the signature**, parses the body, and acts on it.
 
@@ -80,15 +79,17 @@ Assumes you have a `TANGO_API_KEY` and want to receive entity-update webhooks fo
 ```bash
 export TANGO_API_KEY=...
 tango webhooks list-event-types
-# entities.updated         An entity record was updated
-# awards.created           A new award was published
-# ...
+# alerts.opportunity.match   New/updated opportunity matched a saved alert
+# alerts.contract.match      New/updated contract matched a saved alert
+# alerts.entity.match        Entity matched a saved alert
+# alerts.grant.match         Grant matched a saved alert
+# alerts.forecast.match      Forecast matched a saved alert
 ```
 
 ### 2. See what a payload looks like
 
 ```bash
-tango webhooks fetch-sample --event-type entities.updated
+tango webhooks fetch-sample --event-type alerts.entity.match
 ```
 
 Prints the canonical JSON shape Tango will deliver. No POST, no signature — just the body.
@@ -107,26 +108,32 @@ In another shell, drive it with the canonical sample, signed locally:
 ```bash
 tango webhooks simulate \
   --secret $TANGO_WEBHOOK_SECRET \
-  --event-type entities.updated \
+  --event-type alerts.entity.match \
   --to http://127.0.0.1:8011/tango/webhooks
 ```
 
-The listener should print a `verified` delivery with the entities-updated body. You now have a feedback loop: edit your handler, re-run `simulate`, see the result.
+The listener should print a `verified` delivery with the alerts.entity.match body. You now have a feedback loop: edit your handler, re-run `simulate`, see the result.
 
 ### 4. Wire up the real Tango → your handler path
 
-When you're ready for end-to-end testing against Tango itself, expose your local listener via a tunnel (`ngrok http 8011`, `cloudflared tunnel`, etc.) and register that public URL with Tango:
+When you're ready for end-to-end testing against Tango itself, expose your local listener via a tunnel (`ngrok http 8011`, `cloudflared tunnel`, etc.) and register that public URL with Tango, then create an alert via the SDK:
 
 ```bash
 # Use the public URL the tunnel gave you.
 tango webhooks endpoints create --url https://<your-tunnel>.ngrok.io/tango/webhooks
 # Save the `secret` from the response — that's what your handler uses to verify.
+```
 
-tango webhooks subscriptions create \
-  --name "watch UEI ABC123" \
-  --event-type entities.updated \
-  --subject-type entity \
-  --subject-id ABC123
+```python
+# Create an alert (filter subscription) via the SDK
+from tango import TangoClient
+
+client = TangoClient()
+client.create_webhook_alert(
+    name="watch UEI ABC123",
+    query_type="entity",
+    filters={"uei": "ABC123"},
+)
 ```
 
 To force a real test delivery from Tango (without waiting for an actual event):
@@ -194,7 +201,7 @@ Three sources for the payload (mutually exclusive):
 
 | Flag | Source | When to use |
 |---|---|---|
-| `--event-type X` | Fetches the canonical sample for `X` from Tango | You want a realistic body without setting up a subscription |
+| `--event-type X` | Fetches the canonical sample for `X` from Tango | You want a realistic body without setting up an alert |
 | `--payload-file PATH` | Reads a JSON file | You're testing a specific shape (regression, edge case) |
 | *(neither)* | A built-in placeholder envelope | Smoke-testing the wiring |
 
@@ -239,22 +246,27 @@ tango webhooks endpoints delete ENDPOINT_ID [--yes]
 
 `create` returns the generated `secret` once — save it. `delete` prompts for confirmation; `--yes` skips. `--inactive` registers the endpoint disabled (no deliveries until you re-enable it).
 
-### `tango webhooks subscriptions`
+### Managing alerts
 
-Manage **what Tango delivers**.
+Alerts (filter subscriptions) are the canonical way to control what Tango delivers. There is no CLI subgroup for them — use the SDK directly:
 
-```bash
-tango webhooks subscriptions list [--page N] [--page-size N]
-tango webhooks subscriptions get  SUBSCRIPTION_ID
-tango webhooks subscriptions create \
-  --name "watch UEI ABC123" \
-  --event-type entities.updated \
-  --subject-type entity \
-  --subject-id ABC123
-tango webhooks subscriptions delete SUBSCRIPTION_ID [--yes]
+```python
+from tango import TangoClient
+
+client = TangoClient()
+
+client.list_webhook_alerts()
+client.get_webhook_alert("ALERT_UUID")
+client.create_webhook_alert(
+    name="watch UEI ABC123",
+    query_type="entity",
+    filters={"uei": "ABC123"},
+)
+client.update_webhook_alert("ALERT_UUID", name="Renamed")
+client.delete_webhook_alert("ALERT_UUID")
 ```
 
-`create` builds a single-record subscription (one event type, one subject type, one or more subject IDs). For multi-record subscriptions, call `client.create_webhook_subscription(...)` directly with a hand-crafted `payload` dict.
+For multi-endpoint accounts, pass `endpoint=<uuid>` to `create_webhook_alert` to pin which endpoint the alert delivers to.
 
 ---
 
@@ -355,16 +367,19 @@ export TANGO_API_KEY=...
 tango webhooks list-event-types
 # 2. Stand up a tunnel so Tango can reach you
 ngrok http 8011 &
-# 3. Register your endpoint and subscription
+# 3. Register your endpoint
 tango webhooks endpoints create --url https://<id>.ngrok.io/tango/webhooks
 # (save the `secret` from the response into TANGO_WEBHOOK_SECRET)
-tango webhooks subscriptions create \
-  --name "entities" --event-type entities.updated \
-  --subject-type entity --subject-id <UEI>
-# 4. Run the listener pointed at your downstream handler
+# 4. Create an alert via the SDK
+python -c '
+from tango import TangoClient
+TangoClient().create_webhook_alert(
+    name="entities", query_type="entity", filters={"uei": "<UEI>"}
+)'
+# 5. Run the listener pointed at your downstream handler
 tango webhooks listen --port 8011 --secret $TANGO_WEBHOOK_SECRET \
   --forward-to http://localhost:4242/wh
-# 5. Force a test delivery
+# 6. Force a test delivery
 tango webhooks trigger
 ```
 
@@ -377,7 +392,7 @@ You don't need a Tango account or any tunnel:
 tango webhooks listen --port 8011 --secret dev --forward-to http://127.0.0.1:4242/wh
 
 # In another shell, drive it. Use Tango-shaped bodies if you have an API key:
-tango webhooks simulate --secret dev --event-type entities.updated \
+tango webhooks simulate --secret dev --event-type alerts.entity.match \
   --to http://127.0.0.1:8011/tango/webhooks
 
 # Or use a custom shape from a file (no API key required):
@@ -397,7 +412,7 @@ def test_handler_round_trip():
     with WebhookReceiver(secret="s").run() as rx:
         result = simulate.deliver(
             target_url=rx.url,
-            payload={"events": [{"event_type": "entities.updated", "uei": "X"}]},
+            payload={"events": [{"event_type": "alerts.entity.match", "alert_id": "X"}]},
             secret="s",
         )
         assert result.status_code == 200
@@ -407,7 +422,7 @@ def test_handler_round_trip():
 ### "I need to inspect what bytes Tango actually sends"
 
 ```bash
-tango webhooks simulate --secret $TANGO_WEBHOOK_SECRET --event-type entities.updated
+tango webhooks simulate --secret $TANGO_WEBHOOK_SECRET --event-type alerts.entity.match
 # Prints { "delivered": false, "headers": {...}, "sent_payload": {...} }
 ```
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tango-python"
-version = "0.6.0"
+version = "0.7.0"
 description = "Python SDK for the Tango API"
 readme = "README.md"
 requires-python = ">=3.12"