For Operators - Launch personalised promotions directly from Hubconnect!!
Read more
Ctrlk
Knowledge BaseDeveloper DocsProduct NewsChangelogStatusHub88 home
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

This applies to the Operator Generic API: Wallet API, Games API, Freebets API, Transactions API and all other Operator API surfaces.

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.

Next'enabled_currencies' added to Operator Products List API response

Last updated

Was this helpful?