DraxGUI webhooks and Tebex checkout

Operator and developer guide for the two Store & Web logic nodes, Webhook (web.webhook) and Tebex checkout (web.tebex_checkout).

Everything below is covered by automated tests; nothing has been exercised against a live Tebex store or a public webhook receiver (section 8 lists what was and was not tested).

1. What the nodes do

Both nodes pause the flow while the request is in flight (like Wait / Call script), never block the server thread, and resume on the main thread. Every failure takes the failed port when it is wired (otherwise the flow ends) and writes a short reason to the debug trace (debug: true). Reasons are written for the operator and contain no URL path, query, token or secret. They are not shown to players.

If nothing is configured the nodes fail with a message saying what to configure; menus, HUDs, popups, packs and the editor are unaffected. The editor preview never sends a webhook or contacts Tebex ("would run" only).

A project can reference an endpoint by id only. URLs, secrets and tokens exist only in config.yml (or environment variables) and never in projects, exports or packs.

2. Configuration

Add a web: section to plugins/DraxGUI/config.yml. /draxgui reload applies changes (except the two worker limits, which need a restart).

web:
  limits:
    maxConcurrent: 4          # worker threads for outbound calls (restart to change)
    queueSize: 64             # queued calls before new ones fail immediately (restart to change)
    maxBodyBytes: 65536       # upper bound for any webhook body
  egress:
    # Names / IPs / CIDRs that may resolve to private or loopback addresses (see section 3.2).
    allowHosts: []
  webhooks:
    rewards:
      url: https://hooks.example.com/draxgui/rewards
      secretEnv: DRAXGUI_REWARDS_SECRET     # HMAC-SHA256 signing key from the environment (or: secret: "...")
      timeoutMs: 5000
      retries: 0
      includePlayer: false
  tebex:
    enabled: false
    publicTokenEnv: TEBEX_PUBLIC_TOKEN      # or: publicToken: "xxxx-..."
    # privateKeyEnv: TEBEX_PRIVATE_KEY      # optional, see section 6

web.limits

web.egress

web.webhooks.<id>

The id may use letters, digits, _, ., - (max 64). A bad endpoint is disabled with a reason; the others keep working.

web.tebex

Unknown keys are reported as problems at load time (typos are not ignored silently). /draxgui status shows each endpoint's scheme://host, whether it is signed, the Tebex state and all configuration problems, never a secret or URL path.

3. Security model

3.1 Who controls what

A response from a webhook receiver is read (bounded) but never interpreted: it cannot set variables, grant items or run commands. A Tebex response is parsed only for the basket id and the checkout link.

3.2 Egress policy (SSRF)

Every destination is checked on the resolved addresses, not on the text of the URL:

IPv6 forms that carry an IPv4 address (IPv4-mapped ::ffff:a.b.c.d, NAT64 64:ff9b::/96, 6to4 2002::/16) are judged by the embedded IPv4 address, so ::ffff:127.0.0.1 or 64:ff9b::a9fe:a9fe do not bypass the rules. Allowlisting a name (or allowPrivate) only ever unlocks loopback, private and CGNAT addresses for that name; it can never reach metadata or link-local addresses, even if that name later resolves there.

Name and URL rules applied before any DNS lookup: only http/https; http needs allowInsecureHttp; no user:password@; ASCII host names only; IP literals must be canonical (2130706433, 0x7f.0.0.1, 127.1, 010.0.0.1 are refused); localhost, single-label names and *.local, *.localhost, *.localdomain, *.internal, *.home.arpa are refused unless allowlisted. Literal IPs in url / baseUrl are also checked when the configuration loads, so an obviously blocked endpoint is reported at startup.

If a name resolves to several addresses, all of them must be acceptable; one private answer among public ones refuses the host.

3.3 Connection-time validation (DNS rebinding)

java.net.http.HttpClient resolves the host again when it connects and offers no hook between the lookup and the connection, so an address check done first can be defeated by a name that answers differently the second time. DraxGUI therefore uses a small purpose-built HTTP/1.1 client (SafeHttp):

1. check the URL syntax and name rules;
2. resolve the name once (on a bounded resolver pool, inside the call deadline);
3. require every returned address to pass the policy;
4. connect a socket to those exact InetAddress objects (no second lookup); for https, layer TLS on that socket with SNI and certificate verification (HTTPS endpoint identification) for the name in the URL;
5. repeat steps 1-4 for every redirect hop.

The tests prove that the resolver is asked exactly once per hop, that the connection goes to the validated address, and that a name which answers a metadata address on the second lookup (the redirect hop) is refused without any connection. A mutation that connects by name instead of by address makes that test fail.

3.4 Redirects

Only 307 and 308 are followed (they keep the POST method and body). 301, 302 and 303 fail the node because following them would silently turn the delivery into a body-less GET. Each hop is limited by maxRedirects, re-validated like a first request, may not leave the endpoint's host unless followCrossHostRedirects is true, and may never go from https to http.

3.5 Secrets, logging and privacy

• Secrets may be written in config.yml or supplied through environment variables (secretEnv, publicTokenEnv, privateKeyEnv); protect config.yml like any file holding credentials. Nothing is embedded in the plugin, in projects or in exported packs.
• A missing or invalid secret disables only that endpoint: DraxGUI never sends an endpoint unsigned because its secret failed to load.
• Messages, the trace and statusLines() show only scheme://host[:port], endpoint ids and reasons. Request/response bodies, paths, queries, tokens, keys and signatures are not logged. Configuration warnings contain setting names, never values.
• Player name and UUID leave the server only when the endpoint sets includePlayer: true (webhooks) and, for Tebex, the player name that Tebex needs to attribute the basket. The Tebex call sends no UUID or IP address.
• The body is authored by whoever can edit the project. Treat it as that editor's data when you decide whether an endpoint should receive it.

3.6 Bounded resources

All network work runs on maxConcurrent daemon worker threads behind a queueSize queue; a full queue, a per-endpoint maxPending overflow, a minIntervalMs violation or an invalid body fail the node immediately on the calling thread without I/O. One attempt has a single deadline across DNS, connect, TLS handshake, request write and response read (a server that drips bytes cannot extend it). A call as a whole, including retries, has an overall deadline, so a flow can never wait forever; closing the plugin completes every pending call with a failure. Response headers are capped (100 fields, 32 KiB), bodies at maxResponseBytes, JSON bodies at maxBodyBytes, 8 nesting levels and 10,000 values.

3.7 Residual risks and honest limits

• Classification is a list. Future special-use ranges that are not in EgressPolicy.classify would count as public. Keep a network-level egress firewall as defence in depth.
• Allowlists are trust. A name in allowHosts may resolve to any loopback/private/CGNAT address at any time; an IP/CIDR entry (including metadata addresses) is honoured as written.
• Public receivers are public. The policy stops DraxGUI from being pointed at internal services. It cannot stop an administrator-configured public endpoint (or a service that becomes compromised) from receiving the body you send it.
• Trust anchors are the JVM's default trust store; there is no certificate pinning. No client certificates.
• No proxy support. HTTP(S)_PROXY and JVM proxy settings are ignored; an environment that forces outbound traffic through a proxy needs a firewall rule or a custom transport.
• Hand-written HTTP/1.1 client. It is deliberately small (no HTTP/2, no compression, no keep-alive, strict framing that rejects ambiguous responses). Receivers that only speak HTTP/2 are not supported. It has been tested against the JDK's own HttpServer/HttpsServer and byte-exact malformed responses, not against a large corpus of real servers.
• Resolver behaviour. The system resolver (including search domains and the JVM's DNS cache) decides what a name resolves to; the policy then judges that answer. A hung resolver costs one of two resolver threads until the OS gives up; further lookups queue up to 16 and then fail with "resolver busy".
• Replay and duplicates are the receiver's job. DraxGUI signs a timestamp with the body and sends an idempotency key; the receiver must check freshness and deduplicate (sections 4 and 5).
• IDN host names must be written in punycode.
• The browser editor preview and the Bedrock fallback never call these nodes; there is no "live test" command yet.

4. Retry and idempotency policy

Every web.webhook execution gets a random Idempotency-Key (UUID) and a body fixed at that moment. Retries reuse the identical bytes and the identical key, plus X-DraxGUI-Attempt: 1, 2, ....

Retried (only if retries > 0 and attempts remain), after exponential backoff (250 ms base, jitter up to 25%, capped at 5 s):

Never retried: policy refusals, oversized or malformed responses, redirect problems, 500 and every other status, 4xx (except 408/429), and a timeout or connection error after the request was sent (the receiver may already be acting on it).

Consequences:

• Delivery is at-least-once only for the listed transient cases and otherwise at-most-once per node execution. The receiver must deduplicate on Idempotency-Key if it matters.
• Two separate executions (a double click, a reloaded flow) have different keys. Guard reward-like flows with a cooldown / once-per-player variable in the graph or minIntervalMs; a webhook response can never grant a reward by itself.
• A failed outcome does not prove the receiver did nothing (for example after a timeout).

5. Verifying a signed webhook (receiver side)

Headers: X-DraxGUI-Timestamp (Unix seconds), X-DraxGUI-Signature: v1=<hex>, Idempotency-Key. The MAC is HMAC-SHA256(secret, timestamp + "." + rawBody). Compute it over the raw bytes you received, compare in constant time, and reject timestamps outside your tolerance (for example 5 minutes).

import hmac, hashlib, time

def verify(secret: bytes, headers, raw_body: bytes, tolerance=300) -> bool:
    ts = headers["X-DraxGUI-Timestamp"]
    if abs(time.time() - int(ts)) > tolerance:
        return False
    expected = "v1=" + hmac.new(secret, ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers["X-DraxGUI-Signature"])

const crypto = require('crypto');
function verify(secret, headers, rawBody, tolerance = 300) {
  const ts = headers['x-draxgui-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > tolerance) return false;
  const mac = 'v1=' + crypto.createHmac('sha256', secret).update(ts + '.').update(rawBody).digest('hex');
  const a = Buffer.from(mac), b = Buffer.from(headers['x-draxgui-signature'] || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

The body is a JSON object: your map input, with whole numbers written without a fraction (5, not 5.0). A nested map is written as an object; a nested list that happens to consist only of two-element [text, value] pairs with distinct keys is also written as an object, because the runtime represents maps that way (an empty nested map is therefore []). Error values in the body (a failed expression) make the node fail instead of sending null.

6. Tebex

6.1 What DraxGUI does

Adapter headless-v1 uses Tebex's documented Headless API (https://docs.tebex.io/developers/headless-api, read 2026-10-21):

1. POST {baseUrl}/accounts/{publicToken}/baskets with {"username": "<player>"} (Minecraft stores need the username; optional complete_url / cancel_url). The response's data.ident is the basket.
2. POST {baseUrl}/accounts/{publicToken}/baskets/{ident}/packages with {"package_id": "<ident or id>", "quantity": 1}. The response basket carries data.links.checkout.
3. The link must be https (http only with allowInsecureHttp), without credentials, on the default port and on a host matching checkoutHosts; otherwise it is dropped and the node fails. The player then receives one line of plain text (formatting codes and control characters stripped, 128 characters max) with an open_url click and a hover naming the destination host. Vanilla clients ask the player to confirm before opening a chat link (not verified on a client here).

The basket and package idents are validated ([A-Za-z0-9_-]) before they become part of a path, so a hostile response cannot redirect the second call. Recommended package id: the ident (for example pkg_12_456); Tebex documents that idents work for every package type and that standard packages also accept the numeric id.

6.2 What DraxGUI does not do

• It never asks for or sees card details; payment happens on Tebex's checkout page in the player's browser.
• It never marks anything as purchased or grants anything. Fulfilment is Tebex's own delivery (the Tebex game-server plugin / command queue). A menu click, a "success" string, a link having been shown, or any client-supplied value is not proof of payment.
• The private key is not needed for the basket calls (the documentation lists them as public-token calls). If you set one it is sent as HTTP Basic credentials (public token = user name, private key = password) on both calls; leaving it unset is the least-privilege choice.

6.3 Setup

1. In the Tebex creator panel create or open your webstore (Minecraft store type) and note the packages you want to offer; copy each package's ident from the Headless API or the package page.
2. Panel > Developers > API keys: copy the public token. Put it in an environment variable (TEBEX_PUBLIC_TOKEN) or web.tebex.publicToken.
3. Set web.tebex.enabled: true, then /draxgui reload. /draxgui status should show tebex: ready (headless-v1).
4. Use a Tebex checkout node with the package ident in a button flow. Tebex's "Test Payments" payment method (panel > Settings > Checkout > Test Mode) is the documented way to test; test payments create real records and webhook events, and must be removed before the store is public.
5. Make sure Tebex's own game-server delivery plugin is installed and linked; that is what hands the player the product after payment.

6.4 Not verified live (read before relying on it)

No call to Tebex was made from this implementation (no account, no credentials, no money). The adapter follows the documentation but these points are unverified against the real service:

• the exact add-package path: the Tebex guide text shows POST https://headless.tebex.io/api/baskets/{basketIdent}/packages while its OpenAPI excerpt lists {server}/{basketIdent}/packages under /accounts/{token}. DraxGUI uses /accounts/{token}/baskets/{basket}/packages; if Tebex answers 404 use addPackagePath to match your store;
• whether username is accepted in the create-basket body (the guide requires it for Minecraft stores but its schema omits it), and whether Tebex accepts Floodgate/Bedrock-style names (leading . or *);
• the real shape of links.checkout (host names other than *.tebex.io; extend checkoutHosts if needed);
• rate limits (not documented on the pages read), the behaviour of 429 and Retry-After;
• chat-link presentation on real clients (the component is built and unit-tested; no client has displayed it).

If a response does not look as expected the node fails and the trace names the stage ("creating the basket" / "adding the package") and the HTTP status; the title of Tebex's RFC 9457 problem document is included, detail is not.

6.5 Versioning

adapter: headless-v1 is the only supported revision. If Tebex changes its API, a new revision is added next to it (headless-v2) and v1 keeps working for as long as Tebex serves it; the path templates are an operator-level escape hatch for small path changes only.

7. Node reference: failure messages

8. What was tested

Covered by automated tests: the address checks and allowlists, the HTTP and TLS transport (framing, size limits, deadlines, redirects, certificate checks), the Webhook node (headers, bodies, signing, retries, limits), the Tebex flow against a mock of Tebex's documented endpoints, the configuration (including the shipped web: example) and the node flow in the logic engine.

Not tested: a live Tebex store, a public webhook receiver, a Minecraft client showing the chat link, a Bedrock player, a JVM behind a system proxy, very large traffic.