Nord Security Subscription Management API

Endpoints for managing user subscriptions to data breach monitoring services. These operations enable administrators to create, update, and delete subscriptions for email addresses, phone numbers, domains, and sensitive data types. When a subscription is created, Serity automatically sends requests to the user’s webhook whenever new or updated data matches the subscription criteria. The webhook destination must be specified through the APIs user-management endpoints. ### Webhook Requirements To ensure reliable delivery under high load, user webhooks **must support very high request throughput** — at least `100 requests per second`. Serity operates at scale and will **not throttle outbound traffic** based on slow client responses. Frequent `429 Too Many Requests` responses are retried, but they can **clog internal delivery queues**, thus, it is strongly recommended that webhook endpoints are backed by a **message queue** or similar buffering system that can **acknowledge requests immediately** and **process them asynchronously** at the desired pace. This ensures resilience and prevents backpressure issues during high traffic periods. ### Delivery Semantics and Retry Policy - `2XX responses (200–299)` are treated as successful acknowledgements and are not retried. - `404 responses` trigger internal alerts and are **not retried**, as they typically indicate an invalid or deprecated endpoint. - `429 (Too Many Requests)` responses are retried with backoff, but can cause delivery delays if they persist. - `All other 4XX and 5XX responses` are **retried** with exponential backoff. - After prolonged retry failure, events are moved to a **DLQ**. In such cases, the platform team will contact the user. ### Webhook Payload ``` { "subscription_id": "string", "document_type": "email-sha256 | phone-sha256 | cc-argon2id | nin-argon2id | cc-sha1 | nin-sha1", "document_identifier": "string", "operation_type": "update | insert", "databases": [], "credential_lists": [], "malware_logs": [], } ``` By default, users receive only documents with the *insert* operation type. If the corresponding subscription has the dispatch_on_update option enabled, the webhook also sends update events.