cURL

curl --fail-with-body -sS -X POST 'https://webhooks-testnet.lumeus.dev/v1/subscriptions' \
  -H "Authorization: Bearer $LUMEUS_WEBHOOK_KEY" \
  -H 'Idempotency-Key: retry-0001-2026-10-22' \
  -H 'Content-Type: application/json' \
  -d '{"name":"payments","target_url":"https://example.com/webhooks","account":"GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR","event_types":["transfer"]}'

// Node 18+ (ES module)
const res = await fetch('https://webhooks-testnet.lumeus.dev/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUMEUS_WEBHOOK_KEY}`,
    'Idempotency-Key': 'retry-0001-2026-10-22',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "payments",
    "target_url": "https://example.com/webhooks",
    "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
    "event_types": [
      "transfer"
    ]
  }),
});
console.log(res.status, JSON.stringify(await res.json(), null, 2));

import json
import os

import requests

res = requests.post(
    "https://webhooks-testnet.lumeus.dev/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['LUMEUS_WEBHOOK_KEY']}", "Idempotency-Key": "retry-0001-2026-10-22"},
    json={
        "name": "payments",
        "target_url": "https://example.com/webhooks",
        "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
        "event_types": [
            "transfer"
        ]
    },
    timeout=30,
)
print(res.status_code, json.dumps(res.json(), indent=2))

{
  "id": "00000000-0000-4000-8000-000000000000",
  "name": "payments",
  "target_url": "https://example.com/webhooks",
  "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
  "event_types": [
    "transfer"
  ],
  "active": true,
  "created_at": "2026-10-22T09:15:04Z",
  "admission_protocol": 2,
  "version": 1,
  "desired_state": "active",
  "effective_state": "active",
  "slot_state": "sponsored",
  "sponsored": true,
  "metered": false,
  "signing_version": 1,
  "generation": "testnet-2025-12-18-v2",
  "activation_checkpoint": 5331500,
  "effective_checkpoint": 5331500,
  "last_scanned_ledger": 5331500,
  "hmac_secret": "whsec_0000…"
}

Create a subscription

Creates a webhook endpoint that receives a signed POST for every event its filters match, and returns it with its hmac_secret. Save the secret: only this response shows it, and you need it to verify signatures. The endpoint is active at once and receives events from the ledger after activation_checkpoint.

Free plan: one Testnet endpoint; deliveries cost no credits and are capped at 1,000 per organization per UTC day (later matches become free_quota_exhausted coverage gaps). Mainnet needs a paid plan.
Paid plans: 10 (Starter), 50 (Growth), 250 (Scale) or 1,000 (Enterprise) endpoints per network. Testnet deliveries are free; each delivered Mainnet event costs 1 credit.
Retries: resend the same Idempotency-Key and body to get the existing endpoint (200, without the secret); the same key with another body returns 409.
Payloads: token_transfer, contract_event, balance.changed and webhook.test bodies and the signed headers are in the delivery callback of this operation and on Receive webhooks.

POST

subscriptions

cURL

curl --fail-with-body -sS -X POST 'https://webhooks-testnet.lumeus.dev/v1/subscriptions' \
  -H "Authorization: Bearer $LUMEUS_WEBHOOK_KEY" \
  -H 'Idempotency-Key: retry-0001-2026-10-22' \
  -H 'Content-Type: application/json' \
  -d '{"name":"payments","target_url":"https://example.com/webhooks","account":"GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR","event_types":["transfer"]}'

// Node 18+ (ES module)
const res = await fetch('https://webhooks-testnet.lumeus.dev/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUMEUS_WEBHOOK_KEY}`,
    'Idempotency-Key': 'retry-0001-2026-10-22',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "payments",
    "target_url": "https://example.com/webhooks",
    "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
    "event_types": [
      "transfer"
    ]
  }),
});
console.log(res.status, JSON.stringify(await res.json(), null, 2));

import json
import os

import requests

res = requests.post(
    "https://webhooks-testnet.lumeus.dev/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['LUMEUS_WEBHOOK_KEY']}", "Idempotency-Key": "retry-0001-2026-10-22"},
    json={
        "name": "payments",
        "target_url": "https://example.com/webhooks",
        "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
        "event_types": [
            "transfer"
        ]
    },
    timeout=30,
)
print(res.status_code, json.dumps(res.json(), indent=2))

{
  "id": "00000000-0000-4000-8000-000000000000",
  "name": "payments",
  "target_url": "https://example.com/webhooks",
  "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
  "event_types": [
    "transfer"
  ],
  "active": true,
  "created_at": "2026-10-22T09:15:04Z",
  "admission_protocol": 2,
  "version": 1,
  "desired_state": "active",
  "effective_state": "active",
  "slot_state": "sponsored",
  "sponsored": true,
  "metered": false,
  "signing_version": 1,
  "generation": "testnet-2025-12-18-v2",
  "activation_checkpoint": 5331500,
  "effective_checkpoint": 5331500,
  "last_scanned_ledger": 5331500,
  "hmac_secret": "whsec_0000…"
}

Authorizations

Authorization

string

header

required

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

Idempotency-Key

string

required

Required, 1 to 128 characters. Resending the same key with the same body returns the existing endpoint (200, without hmac_secret) instead of creating a second one; the same key with a different body returns 409.

Required string length: 1 - 128

Example:

"retry-0001-2026-10-22"

Body

application/json

target_url

string<uri>

required

Public HTTPS URL. DNS and dial-time SSRF validation reject private targets.

Maximum string length: 2048

name

string

Label for the endpoint, at most 256 bytes.

Maximum string length: 256

account

string

Checksum-valid G/M/C/B/L StrKey.

asset

string

native or CODE:ISSUER. Balance events also accept a C… token contract (a SAC selects its classic asset) or pool:<64 hex>.

contract_addr

string

Checksum-valid C StrKey.

event_types

string[]

Empty means every decoded event type. Token-transfer types: transfer, mint, burn, clawback, fee. Balance events are opt-in: list balance.changed, or balance.changed.fees to include fee-only XLM changes. Any other value selects contract events by their first topic symbol and must be a Soroban symbol (1-32 characters of A-Z, a-z, 0-9 and _); anything else is a 400. A symbol that looks like a misspelled token-transfer type (for example transfers) is accepted with a warnings entry in the response.

Maximum array length: 64

Required string length: 1 - 128

Callbacks

POST

{$request.body#/target_url}delivery

Body

application/json

Option 1
Option 2
Option 3

string

required

Deterministic event identity: {network}:{ledger}:{n} for token_transfer, {network}:{ledger}:ce:{tx}:{op}:{event} for contract_event. Activity and Webhooks give the same on-chain event the same id (same decoder release), so deduplicate on (network, id); after a Testnet reset ledger numbers repeat, so start a new store.

kind

enum<string>

required

Available options:

token_transfer,

contract_event

type

string

required

transfer, mint, burn, clawback, fee, or a custom contract event name.

network

enum<string>

required

Canonical payload vocabulary: pubnet is Mainnet.

Available options:

pubnet,

testnet

ledger

integer

required

Required range: x >= 3

closed_at

string<date-time>

required

tx_hash

string

required

Pattern: ^[0-9a-fA-F]{64}$

tx_index

integer

required

One-based position within the ledger.

operation_index

integer

One-based operation index; absent for transaction-level fee events.

asset

string

native or CODE:ISSUER. May be absent for custom contract tokens.

contract_address

string

from

string

issuer

string

to_muxed_id

string

Unsigned integer string, never a JavaScript number.

to_muxed_address

string

to_muxed_text

string

to_muxed_hash

string

memo_type

string

memo

string

memo_xdr

string

amount

string

Decimal string; seven decimal places for Classic/SAC assets.

amount_raw

string

Exact signed integer string.

topics

any[]

data

any

topics_xdr

string[]

Base64 ScVal XDR.

data_xdr

string

Base64 ScVal XDR; authoritative typed representation.

paging_token

string

Activity collections only; opaque keyset cursor.

Response

200

Delivered: any 2xx answer within 10 seconds counts.

Response

Created and active (effective_state active). hmac_secret is shown only in this response. A retry with the same Idempotency-Key and body answers 200 with the same endpoint, without hmac_secret.

string<uuid>

required

target_url

string

required

HTTPS URL that receives the signed POSTs.

active

boolean

required

True while the endpoint receives events.

created_at

string<date-time>

required

admission_protocol

integer

required

Delivery protocol version (2: deliveries carry a signed context).

version

integer

required

Endpoint version, also in the ETag header. Every change increments it.

desired_state

string

required

What you asked for: active, paused or deleted.

effective_state

string

required

What applies now: active, activating, paused_by_user, paused_by_funding (for example the free daily cap was reached) or deleted.

slot_state

string

required

metered for paid-plan endpoints, sponsored for the free Testnet endpoint, held for prepaid funded endpoints.

Activity API

Assets API

Webhooks

RPC

Account

Create a subscription

Authorizations

Headers

Body

Callbacks

Body

Response

Response