> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumeus.dev/llms.txt > Use this file to discover all available pages before exploring further. # List subscriptions > Returns the organization's webhook endpoints on this network, newest first. Deleted endpoints are left out unless include_deleted=true. ## OpenAPI ````yaml /api-reference/webhooks.json get /v1/subscriptions openapi: 3.0.3 info: title: Lumeus Webhooks API version: '2026-09-15' description: >- Lumeus Webhooks API on Stellar. Sign up at https://app.lumeus.dev: Free, Starter, Growth and Scale plans are self-serve, Enterprise by agreement. - **Pricing.** Testnet webhook deliveries cost no credits. A Free organization gets one Testnet endpoint with up to 1,000 deliveries a day. On paid plans each delivered Mainnet event costs 1 credit from the monthly balance. Calls to this management API are not charged. Plans, limits and credit weights: `GET https://api.lumeus.dev/v1/plans`. - **Authentication.** Send `Authorization: Bearer whk_…`, a webhook key from the dashboard. Webhook keys belong to one network, so pick the server that matches the key. `lum_` API keys are not accepted here (401). - **Headers.** Every response carries X-Request-Id; authenticated responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; 429 and 503 carry Retry-After. - **Errors.** JSON with a machine-readable code (see [errors](/guides/errors)). A path with an empty, `.` or `..` segment answers 400 invalid_request, a trailing slash answers 404 not_found, and a method the path does not accept answers 405 with an Allow header. - **CORS.** Browser calls (CORS) are allowed from https://docs.lumeus.dev (the Try it playground of this reference) and https://app.lumeus.dev only, without cookies; responses expose ETag, Link, Location, Retry-After, X-Request-Id, X-Lumeus-Operation-Id, X-Lumeus-Idempotency and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (errors included). Other websites cannot read responses made with a server key: use a publishable key with your own allowed origins ([browser keys](/guides/browser-keys)). license: name: Lumeus API contract servers: - url: https://webhooks-testnet.lumeus.dev description: Testnet (default) - url: https://webhooks.lumeus.dev description: Mainnet security: - Bearer: [] tags: - name: Webhook keys description: >- Create, list and revoke the `whk_` keys that manage webhook endpoints on one network. - name: Subscriptions description: >- Create, list, read, change, pause and delete webhook endpoints (subscriptions) and their event filters. - name: Deliveries description: >- What was delivered to an endpoint: recent deliveries, coverage gaps and signed test events. - name: Signing keys description: >- Rotate an endpoint's whsec_ signing secret with a 24-hour overlap, or end the overlap early. - name: Replay description: >- Redeliver past events or replay a ledger range to an endpoint, priced by a quote first. Free and paid plan endpoints get 403 today. - name: Health description: Liveness and readiness probes for monitoring. No authentication. paths: /v1/subscriptions: get: tags: - Subscriptions summary: List subscriptions description: >- Returns the organization's webhook endpoints on this network, newest first. Deleted endpoints are left out unless include_deleted=true. operationId: listSubscriptions parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 500 example: 50 description: Endpoints per page, 1 to 500 (default 500). - name: cursor in: query required: false schema: type: string description: next_cursor from the previous page. - name: include_deleted in: query required: false schema: type: boolean example: false description: Include deleted endpoints. Default false. responses: '200': description: A page of endpoints, newest first. content: application/json: schema: type: object properties: subscriptions: type: array items: $ref: '#/components/schemas/Subscription' next_cursor: type: string description: >- Pass as cursor to get the next page; null on the last page. nullable: true required: - subscriptions - next_cursor example: subscriptions: - id: 00000000-0000-4000-8000-000000000000 name: my-app target_url: https://example.com/webhooks asset: native event_types: - transfer active: false created_at: '2026-10-20T09:46:50.582763Z' admission_protocol: 2 version: 2 desired_state: deleted effective_state: deleted slot_state: sponsored sponsored: true signing_version: 1 generation: testnet-2025-12-18-v2 activation_checkpoint: 5293204 effective_checkpoint: 5293284 last_scanned_ledger: 5293284 last_fully_admitted_ledger: 5293271 metered: false - id: 00000000-0000-4000-8000-000000000000 name: my-app target_url: https://example.com/webhooks asset: native event_types: - transfer active: false created_at: '2026-10-20T09:36:42.967981Z' admission_protocol: 2 version: 7 desired_state: deleted effective_state: deleted slot_state: sponsored sponsored: true signing_version: 1 generation: testnet-2025-12-18-v2 activation_checkpoint: 5293082 effective_checkpoint: 5293184 last_scanned_ledger: 5293184 last_fully_admitted_ledger: 5293184 metered: false next_cursor: null headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer '400': $ref: '#/components/responses/HTTP400_4' '401': $ref: '#/components/responses/HTTP401' '403': $ref: '#/components/responses/HTTP403' '405': $ref: '#/components/responses/HTTP405_3' '429': $ref: '#/components/responses/HTTP429' '503': $ref: '#/components/responses/HTTP503_3' x-codeSamples: - lang: bash label: cURL source: >- curl --fail-with-body -sS 'https://webhooks-testnet.lumeus.dev/v1/subscriptions?limit=50' \ -H "Authorization: Bearer $LUMEUS_WEBHOOK_KEY" - lang: javascript label: JavaScript source: >- // Node 18+ (ES module) const res = await fetch('https://webhooks-testnet.lumeus.dev/v1/subscriptions?limit=50', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUMEUS_WEBHOOK_KEY}`, }, }); console.log(res.status, JSON.stringify(await res.json(), null, 2)); - lang: python label: Python source: |- import json import os import requests res = requests.get( "https://webhooks-testnet.lumeus.dev/v1/subscriptions?limit=50", headers={"Authorization": f"Bearer {os.environ['LUMEUS_WEBHOOK_KEY']}"}, timeout=30, ) print(res.status_code, json.dumps(res.json(), indent=2)) components: schemas: Subscription: type: object properties: id: type: string format: uuid name: type: string description: Endpoint label. target_url: type: string description: HTTPS URL that receives the signed POSTs. hmac_secret: type: string description: >- Returned only by the first successful creation; retries do not reveal it. account: type: string description: Account filter, when set. asset: type: string description: Asset filter, when set. contract_addr: type: string description: Contract filter, when set. event_types: type: array items: type: string description: Event type filter; absent or empty means every decoded event type. active: type: boolean description: True while the endpoint receives events. created_at: type: string format: date-time admission_protocol: type: integer description: 'Delivery protocol version (2: deliveries carry a signed context).' version: type: integer description: >- Endpoint version, also in the ETag header. Every change increments it. desired_state: type: string description: 'What you asked for: active, paused or deleted.' effective_state: type: string description: >- What applies now: active, activating, paused_by_user, paused_by_funding (for example the free daily cap was reached) or deleted. slot_state: type: string description: >- metered for paid-plan endpoints, sponsored for the free Testnet endpoint, held for prepaid funded endpoints. sponsored: type: boolean description: >- True for the one free Testnet endpoint of a Free organization: deliveries are not charged credits but are capped per UTC day, and replays are not available. metered: type: boolean description: >- True for a paid-plan endpoint: every delivered Mainnet event costs the catalog webhook credit weight (1 credit) from the organization's monthly balance, with overage billed on paid plans. Testnet deliveries, and failed, cancelled and expired deliveries, cost nothing. Replays are not yet available for paid endpoints. signing_version: type: integer description: Version of the current signing secret; rotation increments it. generation: type: string description: Event index generation the endpoint reads. activation_checkpoint: type: integer description: >- The endpoint receives events from the ledger after this one. Read earlier history from the Activity API. effective_checkpoint: type: integer description: Last ledger the endpoint's state applies to. last_scanned_ledger: type: integer description: Last ledger scanned for matching events. last_fully_admitted_ledger: type: integer description: Last ledger whose matching events were all queued for delivery. free_quota: type: object properties: day: type: string description: UTC date (YYYY-MM-DD). daily_cap: type: integer admitted: type: integer description: >- Admitted today; deliveries cancelled before any attempt are given back. delivered: type: integer required: - day - daily_cap - admitted - delivered description: >- Free Testnet endpoints only, on `GET /v1/subscriptions/{id}`: the organization's admitted and delivered deliveries today (UTC) against its daily cap. paid: type: object properties: plan: type: string endpoint_limit: type: integer description: Paid endpoints allowed per network on this plan. endpoints_used: type: integer description: Active paid endpoints of the organization on this network. credits_per_delivery: type: integer required: - plan - endpoint_limit - endpoints_used - credits_per_delivery description: Paid endpoints only, on `GET /v1/subscriptions/{id}`. warnings: type: array items: type: string description: >- Create and update responses only: non-fatal filter warnings, such as a probable event type typo. required: - id - target_url - active - created_at - admission_protocol - version - desired_state - effective_state - slot_state - sponsored - metered - signing_version Error: type: object properties: error: type: string description: Human-readable message. It may change; branch on code. code: type: string description: >- Machine-readable error code. Branch on code, not on the error text, which may change. RPC carries the same codes as the string error.data of a JSON-RPC error. invalid_request: 400: invalid input, including a malformed Idempotency-Key or an unknown or repeated query parameter (Webhooks also uses it for an oversized request body, 413). Fix the request; do not retry unchanged. unauthorized: 401: missing, revoked, invalid or wrong-network credential. payment_required: 402 (Mainnet): monthly credit quota exhausted on a hard-capped plan. forbidden: 403: the key or account policy does not allow this action. not_found: 404 (Webhooks also 410): the resource does not exist in this organization and network. topic_search_disabled: 404: contract-event topic search is not enabled on this network. method_not_allowed: 405: the route does not accept this method. conflict: 409: conflicting request identity, idempotency key, funding or recovery state. generation_changed: 409: the index generation or network changed since the snapshot was taken; restart the walk without generation and snapshot_ledger. history_unavailable: 409 (Assets): as_of_ledger is not answered from the balance history; start a snapshot job (POST /snapshots) or retry later. precondition_failed: 412 (Webhooks): the subscription version changed; fetch the current ETag. response_too_large: 413: the result exceeds the response budget; lower limit or narrow the request. precondition_required: 428 (Webhooks): If-Match with the subscription ETag is required. rate_limited: 429: a rate, concurrency or credit-cap limit was reached, or (Activity, Assets and RPC on Testnet) the daily Testnet request cap (message `daily Testnet request cap of 10000 reached; resets at 00:00 UTC`, Retry-After until 00:00 UTC). Wait Retry-After seconds (a refused request consumes nothing). A Retry-After greater than 60 means the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. RPC carries it as the string error.data. internal_error: 500 or another unexpected 5xx; quote request_id when contacting support. not_implemented: 501: the feature is not enabled on this host. busy: 503: reads are saturated (the queue wait expired or the database refused another query or ran short of memory). Retry the same request after Retry-After (2) seconds. query_timeout: 503: the read ran out of time. Do not retry unchanged right away: narrow the ledger range (since_ledger/until_ledger) or lower limit; Retry-After is 30. index_not_ready: 503: the index or snapshot is not ready yet or is rebuilding; retry after Retry-After seconds. topic_coverage: 503: the effective range is outside the contract-event topic index coverage (the message states it); pass a range inside it or retry after Retry-After (60) seconds. unavailable: 503: another temporary failure (billing, rate limiter, queue); retry after Retry-After seconds. enum: - invalid_request - unauthorized - payment_required - forbidden - not_found - topic_search_disabled - method_not_allowed - conflict - generation_changed - history_unavailable - precondition_failed - response_too_large - precondition_required - rate_limited - internal_error - not_implemented - busy - query_timeout - index_not_ready - topic_coverage - unavailable request_id: type: string description: >- Identifier of this request, the same value as the X-Request-Id header. Quote it when contacting support. required: - error responses: HTTP400_4: description: >- Invalid input (code invalid_request). The message names the problem. Fix the request; do not retry it unchanged. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_request error: limit must be an integer from 1 to 500 request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP401: description: >- Missing, invalid, revoked or expired key, or a key for the other network (code unauthorized). Keys work only on the network they were created for. content: application/json: schema: $ref: '#/components/schemas/Error' examples: No key: summary: No key value: code: unauthorized error: missing credentials request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Invalid key: summary: Unknown, revoked or expired whk_ key value: code: unauthorized error: invalid or revoked API key request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP403: description: >- This key or account cannot call this route (code forbidden): for example a read-only key on a workspace route, or a publishable key on a route or from an origin it does not allow. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: forbidden error: confirm your email address to manage webhooks request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP405_3: description: >- This path does not accept the HTTP method you sent (code method_not_allowed). The Allow header lists the methods it accepts. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: method_not_allowed error: >- method PUT is not allowed on /v1/subscriptions; allowed: GET, HEAD, POST request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP429: description: >- The Webhooks management rate limit was reached (code rate_limited). Wait Retry-After seconds. The daily Testnet request cap of Activity, Assets and RPC does not apply to the Webhooks API. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limited error: webhook management rate limit exceeded request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer HTTP503_3: description: >- Temporarily unavailable (code unavailable), for example the management limiter or the database. Wait Retry-After seconds and retry. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unavailable error: webhook control is temporarily unavailable request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ Retry-After: description: Seconds to wait before retrying. schema: type: integer securitySchemes: Bearer: type: http scheme: bearer description: >- Send `Authorization: Bearer whk_…`, a webhook key from the dashboard. Webhook keys belong to one network, so pick the server that matches the key. `lum_` API keys are not accepted here (401). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.