> ## 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. # Update a subscription > Changes an endpoint's name, target URL or filters, or pauses (state paused) or resumes (state active) it. Any other state answers 400 with the message `state must be active or paused; to delete an endpoint use DELETE /v1/subscriptions/{id}`. Send the current ETag as If-Match. Events matched while the endpoint is paused are not delivered later: they are recorded as paused_by_user coverage gaps. A request already in flight may still finish; inspect in_flight_attempts and pending_cancellation. Resending the same Idempotency-Key does not apply the change again. ## OpenAPI ````yaml /api-reference/webhooks.json patch /v1/subscriptions/{id} 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/{id}: patch: tags: - Subscriptions summary: Update a subscription description: >- Changes an endpoint's name, target URL or filters, or pauses (state paused) or resumes (state active) it. Any other state answers 400 with the message `state must be active or paused; to delete an endpoint use DELETE /v1/subscriptions/{id}`. Send the current ETag as If-Match. Events matched while the endpoint is paused are not delivered later: they are recorded as paused_by_user coverage gaps. A request already in flight may still finish; inspect in_flight_attempts and pending_cancellation. Resending the same Idempotency-Key does not apply the change again. operationId: updateSubscription parameters: - name: id in: path required: true description: >- Endpoint (subscription) ID from `POST /v1/subscriptions` or `GET /v1/subscriptions`. The example ID is a placeholder and answers 404: use your own. schema: type: string format: uuid example: 00000000-0000-4000-8000-000000000000 x-default: 00000000-0000-4000-8000-000000000000 example: 00000000-0000-4000-8000-000000000000 - name: Idempotency-Key in: header required: true description: >- Required. Choose one key per change and resend it unchanged on a retry: the same key with the same request returns the first result instead of applying the change again, and the same key with a different request returns 409. schema: type: string minLength: 1 maxLength: 128 example: retry-0001-2026-10-22 x-default: retry-0001-2026-10-22 example: retry-0001-2026-10-22 - name: If-Match in: header required: true description: >- The ETag from `GET /v1/subscriptions/{id}`, for example `"1"` (the weak form `W/"1"` that some proxies produce is accepted too). A stale version returns 412; a missing header returns 428. schema: type: string pattern: ^(W/)?"[1-9][0-9]*"$ example: '"1"' x-default: '"1"' example: '"1"' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionChange' example: state: paused responses: '200': description: The changed endpoint. content: application/json: schema: $ref: '#/components/schemas/ControlResult' example: subscription: id: 00000000-0000-4000-8000-000000000000 name: payments target_url: https://example.com/webhooks account: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR event_types: - transfer active: false created_at: '2026-10-22T09:15:04Z' admission_protocol: 2 version: 2 desired_state: paused effective_state: paused_by_user slot_state: sponsored sponsored: true metered: false signing_version: 1 generation: testnet-2025-12-18-v2 activation_checkpoint: 5331500 effective_checkpoint: 5331620 last_scanned_ledger: 5331620 last_fully_admitted_ledger: 5331620 in_flight_attempts: 0 pending_cancellation: false 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 ETag: description: Quoted subscription version. schema: type: string example: '"1"' Location: schema: type: string '400': $ref: '#/components/responses/HTTP400_6' '401': $ref: '#/components/responses/HTTP401' '403': $ref: '#/components/responses/HTTP403' '404': $ref: '#/components/responses/HTTP404_2' '405': $ref: '#/components/responses/HTTP405_4' '409': $ref: '#/components/responses/HTTP409_2' '410': $ref: '#/components/responses/HTTP410_2' '412': $ref: '#/components/responses/HTTP412' '413': $ref: '#/components/responses/HTTP413' '428': $ref: '#/components/responses/HTTP428' '429': $ref: '#/components/responses/HTTP429' '503': $ref: '#/components/responses/HTTP503_3' x-codeSamples: - lang: bash label: cURL source: >- # Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404. curl --fail-with-body -sS -X PATCH 'https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000' \ -H "Authorization: Bearer $LUMEUS_WEBHOOK_KEY" \ -H 'Idempotency-Key: retry-0001-2026-10-22' \ -H 'If-Match: "1"' \ -H 'Content-Type: application/json' \ -d '{"state":"paused"}' - lang: javascript label: JavaScript source: >- // Node 18+ (ES module) // Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404. const res = await fetch('https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUMEUS_WEBHOOK_KEY}`, 'Idempotency-Key': 'retry-0001-2026-10-22', 'If-Match': '"1"', 'Content-Type': 'application/json', }, body: JSON.stringify({ "state": "paused" }), }); console.log(res.status, JSON.stringify(await res.json(), null, 2)); - lang: python label: Python source: >- # Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404. import json import os import requests res = requests.patch( "https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000", headers={"Authorization": f"Bearer {os.environ['LUMEUS_WEBHOOK_KEY']}", "Idempotency-Key": "retry-0001-2026-10-22", "If-Match": "\"1\""}, json={ "state": "paused" }, timeout=30, ) print(res.status_code, json.dumps(res.json(), indent=2)) components: schemas: SubscriptionChange: type: object properties: name: type: string target_url: type: string format: uri maxLength: 2048 account: type: string description: Empty clears this selector. asset: type: string description: Empty clears this selector. contract_addr: type: string description: Empty clears this selector. event_types: type: array items: type: string state: type: string enum: - active - paused pending_policy: type: string description: >- What happens to deliveries already queued: drain_old still sends them, cancel_old cancels those not yet attempted. Required when target_url changes; optional when a selector (account, asset, contract_addr, event_types) changes (default drain_old); rejected with 400 when neither changes. A change that alters nothing returns 200 with the version unchanged. enum: - drain_old - cancel_old additionalProperties: false ControlResult: type: object properties: subscription: $ref: '#/components/schemas/Subscription' in_flight_attempts: type: integer pending_cancellation: type: boolean warnings: type: array items: type: string description: Non-fatal filter warnings for this change. required: - subscription - in_flight_attempts - pending_cancellation 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_6: 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: >- state must be active or paused; to delete an endpoint use DELETE /v1/subscriptions/{id} 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}$ HTTP404_2: description: Not found in this organization and network (code not_found). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_found error: subscription not found 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_4: 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 POST is not allowed on /v1/subscriptions/00000000-0000-4000-8000-000000000000; allowed: DELETE, GET, HEAD, PATCH 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}$ HTTP409_2: description: The request conflicts with the current state (code conflict). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: conflict error: request identity or subscription generation conflicts 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}$ HTTP410_2: description: >- The resource was deleted, or the retained payload or result expired (code not_found). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_found error: subscription is deleted 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}$ HTTP412: description: >- The subscription version changed (code precondition_failed). Fetch the current ETag and retry. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: precondition_failed error: subscription version changed; fetch its current ETag 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}$ HTTP413: description: Request body too large (code invalid_request). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_request error: request body is too large 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}$ HTTP428: description: If-Match is required (code precondition_required). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: precondition_required error: If-Match with the subscription ETag is required 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.