Skip to main content
Lumeus Webhooks push decoded Stellar events to your HTTPS endpoint a few seconds after each ledger closes. You choose what to receive with filters (an account, an asset, a contract and event types); every delivery is signed, and failed deliveries are retried. To set one up in five minutes, follow Your first webhook.

​
What you can receive

Each delivery body is one JSON event object. Pick the kinds you want with event_types; an empty or omitted list receives every decoded event that matches your other filters. A value that fits none of these, such as balance.everything or my-event, returns 400. A value that is a valid contract event name but looks like a typo of a token type, such as transfers or Mint, is accepted, and the response carries a warnings array that says what it will match. Filters combine with AND:

​
Sample payloads

A token transfer (the body of a transfer delivery):
A contract event (the body of an approve delivery):
The fields are those of the Activity API event model, without the Activity paging fields. Token events can also carry memo and muxed destination fields (memo_type, memo, to_muxed_id, to_muxed_address). On Mainnet, network is pubnet. Amounts are strings; parse them as exact decimals or integers.

​
Plans

  • Free. When a ledger’s matches would pass the day’s 1,000, that ledger is skipped (a free_quota_exhausted coverage gap) and the endpoint shows effective_state: "paused_by_funding" until 00:00 UTC. GET /v1/subscriptions/{id} reports the day’s usage in free_quota. A second Free endpoint, or one on Mainnet, returns 403.
  • Paid plans. Mainnet deliveries draw from your organization’s monthly credit balance (see Plans and billing); Testnet deliveries cost 0 credits. Failed, cancelled and expired deliveries cost nothing, and the retries of one event are charged once. Upgrading keeps your Free Testnet endpoint; new endpoints count against the plan. Moving back to Free pauses paid endpoints (plan_not_entitled coverage gaps) until you upgrade again; nothing is deleted.
Webhooks use their own whk_ key, created per network in the dashboard under Webhooks > Webhook keys. lum_ API keys do not manage webhooks.

​
Go live on Mainnet

The API, payloads and signatures are the same on both networks. The host selects the network; there is no network field (an unknown body field returns 400 with invalid JSON body: unknown field "network"). To move a Testnet integration to Mainnet:
  1. Upgrade the organization to a paid plan.
  2. Create a Mainnet whk_ key and point WEBHOOKS_URL at https://webhooks.lumeus.dev.
  3. Deploy your receiver at a stable public HTTPS URL (not a tunnel), with events stored under a database unique key (see Deduplicate).
  4. Create the subscription on the Mainnet host and store its hmac_secret in your secret manager. Send a test event, then watch deliveries.

​
Delivery guarantees

  • At least once. An event can arrive more than once, for example when your acknowledgement is lost. Deduplicate on (network, id); see Receive and verify.
  • In order per endpoint. Each endpoint has exactly one delivery in flight, sent in ledger order. The next event goes out when your receiver answers the previous one, so an endpoint’s throughput is set by your response time. Answer fast, and split busy filters across several endpoints.
  • Retried, then dead. A failed attempt is retried, up to 8 attempts over about 4 minutes; then the delivery is dead and the next event goes out. Details in Receive and verify.
  • From activation onward. Live matching starts after the subscription’s activation_checkpoint ledger. Read earlier events from Activity history.
  • Up to 4,096 events per ledger per endpoint. A ledger with more matches is recorded as a payload_or_policy_limit coverage gap; narrow the filters.

​
Next