Skip to main content

Webhooks

Webhooks allow Hubble to push updates to your system in real time. Strongly recommended for a production-grade integration.

Authentication​

Each webhook request includes a X-Verify header containing an HMAC-SHA256 signature of the payload, encoded in Base64.

Signature Verification​

Partners must verify the signature using the shared secret key to confirm authenticity:

private fun generateSignature(payload: String, secret: String): String {
    val algorithm = "HmacSHA256"
    val secretKeySpec = SecretKeySpec(secret.toByteArray(), algorithm)
    val mac = Mac.getInstance(algorithm).apply { init(secretKeySpec) }
    val signatureBytes = mac.doFinal(payload.toByteArray())
    return Base64.getEncoder().encodeToString(signatureBytes)
}

IP Whitelisting (Optional)​

Partners can whitelist Hubble's production IP addresses for additional security:

Production IPs:

  • 35.200.156.199
  • 34.47.147.244
  • 34.14.138.52

Add these IPs to your firewall or security group rules to allow incoming webhook requests from Hubble.

Available Webhooks​

WebhookTriggers When...
Brand UpdatedA brand's status, denomination, or amount restrictions change
Wallet Low BalanceWallet balance falls below your configured threshold
Order Reached Terminal StateA PROCESSING order transitions to SUCCESS or FAILED
Brand Discount UpdateSubvention/discount percentage changes for a brand
Staging vs Production Webhooks

Webhook endpoints are configured per environment. Staging webhooks must be configured separately from production.

1. Brand Updated​

Webhook to notify changes in brand properties.

Payload​

{
  "id": "brand_id",
  "denominationType": "FIXED",
  "status": "ACTIVE",
  "denominations": [100, 1000, 5000],
  "amountRestrictions": {
    "minOrderAmount": 100,
    "maxOrderAmount": 5000,
    "minVoucherAmount": 100,
    "maxVoucherAmount": 5000,
    "maxVouchersPerOrder": 5,
    "maxVouchersPerDenomination": 1,
    "maxDenominationsPerOrder": 1
  }
}
note

The fields minAmount and maxAmount in the amountRestrictions object are deprecated. Use minOrderAmount and maxOrderAmount instead.

Handling Brand Updates​

  • Update your local brand cache immediately
  • If status changes to INACTIVE, remove brand from user-facing catalog
  • Validate denomination changes before placing new orders

2. Wallet Low Balance Notification​

Webhook to alert when wallet balance falls below your configured threshold.

Payload​

{
  "balance": 50,
  "threshold": 100
}

Handling Low Balance​

  • Alert your operations team
  • Initiate wallet top-up process
  • Consider pausing order placement if balance is critically low
Configure Your Threshold

Work with your Hubble account manager to set an appropriate threshold based on your order volume. For high-volume operations, set the threshold higher to allow time for top-up.

3. Order Reached Terminal State​

If an order goes into PROCESSING state during generation, once it reaches a terminal state (SUCCESS or FAILED), Hubble sends a notification via webhook.

Payload​

{
  "id": "order_id",
  "status": "SUCCESS"
}
referenceId Not in Webhook Payload

The webhook sends orderId and status, but not your referenceId. Use the orderId to look up the full order via the Get Order API.

Handling Order Terminal State​

  1. Extract the orderId from the webhook payload
  2. Call GET /v1/partners/orders/:orderId to fetch full order details
  3. If SUCCESS, extract and display vouchers to the customer
  4. If FAILED, handle the error and notify the customer

4. Brand Discount Update​

Webhook to notify when subvention/discount percentage changes for a brand.

Payload​

{
  "brandId": "01HFV6NGBFGATYAKZ3AKASJVM9",
  "subventionPercentage": 8,
  "validFrom": "2025-12-23",
  "validTo": "2026-02-28"
}

Note: validTo is optional and may not be present for indefinite discounts.

Catalog Sync Recommendations​

Webhooks are not the only source of truth for catalog changes:

  • Refresh your full catalog at least once per week (daily recommended)
  • Subscribe to the Brand Updated webhook for real-time changes to status, denominations, and amount restrictions
  • Categories are NOT communicated via webhooks — rely on periodic sync for category and new brand additions
  • Filter out INACTIVE brands from your user-facing catalog immediately when detected
Stale Catalog Causes Order Failures

If your sync is infrequent and you miss webhook updates, orders will fail with E150 (denomination not available) or E102 (brand not active).

Retry Policy​

Hubble does not retry failed webhook deliveries. If your endpoint is unavailable or returns an error, the failed webhook is logged but not re-sent.

Implementation Checklist​

  • Set up webhook endpoints on your server
  • Implement signature verification using the shared secret
  • Configure webhook URLs in the Hubble integration portal
  • Handle Brand Updated: update local brand cache
  • Handle Wallet Low Balance: alert team and initiate top-up
  • Handle Order Terminal State: fetch full order and process
  • Implement fallback polling for critical flows
  • Set up logging for all webhook events