> For the complete documentation index, see [llms.txt](https://docs.hub88.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hub88.io/api-changelog/october-2026/operator-api-your-integration-must-ensure-forward-compatibility.md). # Operator API: your integration must ensure forward compatibility Announced: October 5, 2026 **Action required by: 20 October 2026** *** We regularly extend the Operator API with new optional fields to support new features. These are additive, non-breaking changes. \ \ However, integrations that validate our payloads strictly and reject any unknown field can fail when a new field appears. This notice sets out what we expect from every Operator integration, and what to change if your implementation validates strictly today. {% hint style="info" %} **This applies to the Operator Generic API:** \ Wallet API, Games API, Freebets API, Transactions API and all other Operator API surfaces. {% endhint %} ## **What's changing?** As part of normal API evolution, Hub88 may add new optional fields to: * **Requests Hub88 sends to you.** This includes Wallet API calls to your endpoints, such as `/transaction/bet`, `/transaction/win`, `/transaction/rollback` and `/user/balance`. * **Responses Hub88 returns to you.** This includes Games API, Freebets API and Transactions API responses. We may also add new values to existing enum-like fields. These changes are made without a version bump. Your integration must accept them without failing. *** ## **Why is it changing?** Until now, our documentation hasn't stated how Operators should handle new fields. Some serialisation libraries reject unknown fields by default, including Java/Jackson, where `FAIL_ON_UNKNOWN_PROPERTIES` is enabled by default. The Wallet API carries the most risk. If your wallet rejects a Hub88 request because it contains a new field, bets, wins and rollbacks can fail in production. We're making the rule explicit so that every integration is built for it. *** ## **Impact** * **If your integration already ignores unknown fields,** no action is needed. * **If your integration uses strict schema validation,** a future Hub88 release that adds a field could cause your requests to fail. Common examples are Jackson with default settings, Go's `DisallowUnknownFields`, Pydantic `extra="forbid"`, and custom JSON Schema validators with `additionalProperties: false`. On the Wallet API, a failed request means a failed bet, win or rollback. *** ## ⚠️ **Action required by 20 October 2026** Review how your integration deserialises Hub88 payloads, and make sure that: 1. **Unknown fields are ignored, not rejected.** 2. **New values in enum-like fields are handled where possible.** 3. **`X-Hub88-Signature` is verified against the raw request body.** Always verify the signature against the exact bytes you received, before deserialising. If you deserialise first and then re-serialise the object to verify it, any unknown fields you drop will change the body, and signature verification will fail. After 20 October 2026, Hub88 will continue to add optional fields as described above. An integration that rejects unknown fields may fail when those fields are released. #### Technical Guidance The examples below target the following current language/framework versions. Implementations using older major versions should consult the corresponding version-specific documentation, as JSON deserialization defaults and APIs differ between major releases. * **Java — JDK 25+ with Jackson Databind 3.2.x** * Configure Jackson to tolerate fields added to the API response. In Jackson 3.x, unknown JSON properties are ignored by default, so no additional configuration is required for this behavior. If the application explicitly enables strict unknown-property handling, ensure that `FAIL_ON_UNKNOWN_PROPERTIES` is disabled. * For individual models where the behavior should be explicit, use the Jackson 3.x equivalent of `@JsonIgnoreProperties(ignoreUnknown = true)`. * For enum-like fields, do not assume that the server will never introduce new values. Use a nullable/fallback representation or an explicit custom deserializer where appropriate. If using Jackson enum deserialization, configure an appropriate unknown-enum fallback rather than allowing a newly introduced value to fail the entire response. * **Important:** verify `X-Hub88-Signature` against the **raw HTTP request body bytes**, before JSON deserialization. Do not deserialize and re-serialize the request body and then calculate the signature, because unknown fields, field ordering, whitespace, escaping, or other serialization differences can change the signed payload. Jackson's JSON deserialization should therefore happen only after signature verification. * **Go — Go 1.27+ (`encoding/json`)** * The standard `encoding/json` decoder ignores unknown JSON object fields when unmarshalling into a struct by default. **Do not call `Decoder.DisallowUnknownFields()`** for Hub88 API responses, as doing so would make the client incompatible with newly added response fields. * If the application uses the newer `encoding/json/v2` API, retain its default behavior of ignoring unknown members; do not enable `RejectUnknownMembers` for these API responses. * For enum-like fields represented by a custom Go type, implement unmarshalling so that an unknown string value does not cause the entire response to fail. Prefer a fallback such as an `Unknown` value or preserve the raw string where the business logic permits. * **Important:** verify `X-Hub88-Signature` against the **raw HTTP request body bytes** before calling `json.Unmarshal`/`Decoder.Decode`. Never marshal the decoded Go struct back to JSON and use that output for signature verification. * **Python — Python 3.13+ with Pydantic 2.13.x** * Configure Pydantic models to ignore additional fields using `ConfigDict(extra='ignore')`. This is also Pydantic's default behavior, but specifying it explicitly is recommended for API models where forward compatibility is an intentional requirement. * Do **not** use `extra='forbid'` for Hub88 API responses, because a newly introduced response field would cause validation to fail. * For enum-like fields, avoid making the model fail solely because Hub88 introduces a new value. Where appropriate, model the field as a string or provide a custom validation strategy that preserves an unknown value/falls back to an `UNKNOWN` representation. * **Important:** verify `X-Hub88-Signature` against the **raw HTTP request body bytes** before passing the payload to `model_validate_json()` or another Pydantic validation method. Do not validate, convert, and then re-serialize the Pydantic model for signature verification. **General rule:** Hub88 response models must be **forward-compatible with additive changes**. Clients should ignore unknown response fields and tolerate newly introduced enum-like values where the field's semantics allow it. Signature verification is separate from deserialization and must always operate on the original raw request body. *** If you have any questions or need support updating your integration, please contact your Hub88 account manager or our technical support team. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hub88.io/api-changelog/october-2026/operator-api-your-integration-must-ensure-forward-compatibility.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.