Webhooks

Overview

If a partner is interested in receiving real-time callbacks from Hubble, they can share a webhook URL with us. Hubble will send POST requests to this URL for supported events.

All webhooks are signed using an HMAC signature, and partners are expected to verify the request authenticity using the X-Verify header.

---

Transaction Webhooks

Triggered whenever a transaction occurs via the Hubble SDK.

Sample Payload

{
  "transactionReferenceId": "01HRVY38NCAANDYPN3WVGJCDSG",
  "userId": "01HRW71319JNKJS6D3Q85X780R",
  "amount": "1000",
  "discountAmount": "50",
  "timestamp": "2018-06-13T12:11:13",
  "vouchers": [
    {
      "id": "01HZ46Q0P0242STC8TBV926M8C",
      "brandId": "01JRSY42BBMKC2YS9TXMYSYN83",
      "brandName": "Swiggy",
      "cardType": "CARD_NUMBER_SECURED",
      "cardNumber": "5333644476668777",
      "cardPin": "123456",
      "validTill": "2025-04-04",
      "amount": "1000",
      "shareImageUrl": "https://gullak-assets.s3.ap-south-1.amazonaws.com/share-wa-brand-images/Swiggy.jpg",
      "brandRetailModes": ["online", "offline", "app", "website"]
    }
  ]
}

Note: brandRetailModes can be null and must be treated as flexible tags, not a strict enum.

---

Brand Update Webhooks

Used to notify partners of catalog changes such as discount updates, new brand additions, or brand deactivation.

Supported Events & Sample Payloads

1. USER_DISCOUNT_UPDATED

{
  "event": "USER_DISCOUNT_UPDATED",
  "details": {
    "id": "01GMAVS2CHXR0XP1BZSTA9A44K",
    "name": "Amazon shopping",
    "discountPercentage": 5
  }
}

2. NEW_BRAND_CREATED

{
  "event": "NEW_BRAND_CREATED",
  "details": {
    "id": "01GMAVS2CHXR0XP1BZSTA9A44K",
    "name": "Amazon shopping",
    "discountPercentage": 2
  }
}

3. BRAND_DISABLED

{
  "event": "BRAND_DISABLED",
  "details": {
    "id": "01GMAVS2CHXR0XP1BZSTA9A44K",
    "name": "Amazon shopping"
  }
}

---

Webhook Authentication

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

Signature Generation Logic

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)
}

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

---

IP Whitelisting (Optional)

Hubble can also share its outbound IP address for partners who prefer to whitelist incoming webhook sources.