Subscription API
Configure HTTPS receivers, test delivery, enable subscriptions, and rotate signing secrets.
Subscriptions deliver selected observations to a customer-owned HTTPS receiver. Management keys and webhook signing secrets have separate roles.
Use the shared request contract for authentication, pagination, preconditions, idempotency, and common errors. Exact response members are defined in API data types and the downloadable OpenAPI contract.
List subscriptions
/api/v1/connector/organizations/{organization_id}/subscriptionsLists visible subscriptions without secret material or full destination URLs.
limitintegeroptionalNumber of records; bounds are inclusive.
50rule1–200cursorstringoptionalOpaque continuation; preserve the original filters.
Returns a data array of Subscription records, pagination.next_cursor, and request_id.
Create a subscription
/api/v1/connector/organizations/{organization_id}/subscriptionsCreates a disabled receiver and reveals its initial signing secret once.
Requires Idempotency-Key.
An enabled initial value returns 422 test_required. URL validation rejects credentials, private or local addresses, unsupported schemes, and redirects. Test the saved URL before enabling.
If the one-time secret response is lost, read the subscription ID from its idempotent retry, rotate its secret, and revoke the unseen version; replay never repeats secret plaintext.
connection_idstringrequiredConnection whose approved events are delivered.
destination_urlstringrequiredPublic HTTPS receiver without credentials; private addresses and redirects are rejected.
event_typesstring[]requiredExplicit types; subscription.test is reserved for test requests.
enabledbooleanoptionalCreation must use false; enabling requires a successful test.
falseReturns data as SubscriptionCreated, plus request_id.
Read a subscription
/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}Returns saved filters, destination host, enabled state, and test status.
Returns data as Subscription, plus request_id.
Update a subscription
/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}Updates receiver configuration or enabled state.
Requires If-Match from a current read.
Omitted fields remain unchanged. URL or filter changes disable delivery and reset test_state to not_tested; do not combine them with enabled: true. Enabling before a delivered test returns 409 test_required.
Disabling stops subsequent scheduling; in-flight attempts can already have reached the receiver.
destination_urlstringoptionalReplacement public HTTPS receiver; clears the successful test.
event_typesstring[]optionalReplacement selection; changing it clears the successful test.
enabledbooleanoptionaltrue requires a successful test for the saved URL and filters; false stops subsequent deliveries.
Returns data as Subscription, plus request_id.
Test a subscription
/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/testSends a signed synthetic subscription.test event while normal delivery is disabled.
Requires Idempotency-Key.
The test uses the saved URL and active signing secret. Poll the operation, then read the subscription for test_state: delivered. An HTTP acknowledgement proves receiver admission, not downstream processing.
reasonstringrequiredAudited reason; empty values are rejected.
Returns operation.id for operation polling and request_id; acceptance does not establish completion.
Create a signing secret
/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/signing-secretsCreates and activates a replacement signing version, revealed once.
Requires If-Match from a current read. Requires Idempotency-Key.
Use the subscription ETag. At most 2 versions can be active; another returns 409 secret_limit.
New attempts use the replacement. Install it in the receiver, send a test, confirm its secret ID in receiver logs, then revoke the previous version. Keep the previous verifier only until that check succeeds.
reasonstringrequiredAudited reason; empty values are rejected.
Returns data as SigningSecret, plus request_id.
List signing secret versions
/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/signing-secretsLists version IDs and creation times without plaintext.
limitintegeroptionalNumber of records; bounds are inclusive.
50rule1–200cursorstringoptionalOpaque continuation; preserve the original filters.
Returns the response defined by the API data types and downloadable contract.
Revoke a signing secret
/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/signing-secrets/{secret_id}Revokes the selected signing version.
Requires If-Match from a current read.
Use the subscription ETag.
Removing the last active version while enabled returns 409 secret_in_use. For a compromised last secret, disable delivery first, then revoke it. Remove the version from the receiver verifier as well.
Returns no body.
Delete a subscription
/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}Deletes a disabled subscription after deliveries finish or are suppressed.
Requires If-Match from a current read.
Enabled delivery or unresolved attempts return 409 subscription_in_use. Disable, inspect deliveries, and resolve their outcomes before deletion.
Returns no body.