Gameball Developers Guide
v3.0
v3.0
  • Introduction
  • What's New in V3.0
  • Installing Gameball
    • Web
      • Show Gameball Customer Widget
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Go-Live Checklist
    • iOS
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
      • Go-Live Checklist
    • Android
      • Getting Started
      • Initialize Gameball SDK
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Referrals
      • Push Notifications
      • Go-Live Checklist
    • React Native
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
      • Go-Live Checklist
      • Migration from v1 to v2
    • Flutter
      • Getting Started
      • Initialize Gameball SDK
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Referrals
      • Go-Live Checklist
    • Generic Mobile App
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
    • Retail & Modern POS
      • Initialize Gameball Customer Profile
      • Track Orders & Cashback Reward
      • Track Refunds
      • Enable Redemption
        • Prepare POS for Redemption
        • Using Virtual ID
          • Using Virtual Card
  • REST API
    • Overview
      • Server-Side SDKs
    • Authentication
    • API Reference
      • Customer
      • Event
      • Transactions
      • Order
      • Coupons
      • Leaderboard 👑
      • Notifications 👑
      • Configurations 👑
      • Batches 👑
        • Batch Operations Data
      • OTP
      • Partner 🤝
        • Client 🤝
        • Redemption Rule 🤝
        • Cashback Rule 🤝
    • Webhooks
      • Notifications Webhook
      • Customer Profile Webhook
    • Errors
    • Object Reference
  • Tutorials
    • Build Custom UI Elements 👑
      • Display Reward Campaign Progress
      • Show VIP Tiers
      • Show Customer Points Balance
      • Build Leaderboards
      • Show Notifications Inbox
      • Adapt UI to Configurations
      • Advanced UI Techniques
        • Increase Sales with Cashback UI Elements
        • Derive Engagement with Rewards Campaigns UI Elements
    • Tracking Customer Events
    • Build your Own Notification System
    • Checkout Integration Example
    • Redemption Integration Options
      • Redeem with coupon system
        • Integrate your coupon system
          • Example using e-commerce platform(WooCommerce)
          • Example using a custom coupon system
        • Build couponing experience
          • Using Gameball widget
          • Build custom experience
            • Showing customers available points
            • Allowing customers to create coupons
            • Apply the discount code to your cart
        • Coupon integration reference
      • Redeem with direct debt
        • Get customers points balance
        • Redeem customer points
  • Third Party Integrations
    • Segment Integration
Powered by GitBook
On this page
  • Supported Webhook Events
  • Creating an Endpoint for Webhooks
  • Configuring Webhooks
  • Receiving a Webhook
  • Verifying Webhooks
  • Webhooks Retry Policy
  1. REST API

Webhooks

Use our webhooks to subscribe to receive notifications for events in Gameball application.

PreviousCashback Rule 🤝NextNotifications Webhook

Last updated 3 months ago

You can use webhook subscriptions to receive notifications for particular events in Gameball. After you have subscribed to a webhook, your app can execute a specific code immediately after specific events occur in Gameball. Common webhook use cases include sending notifications to IM clients and pagers.

After you , the events that you specified will trigger a webhook notification each time they occur. This notification contains a JSON payload, and HTTP headers that provide context. Webhook includes the following header with example value:

X-GB-Signature: ff7b2ea889c68c80844ee89eab625e8fc53fdc3c

Supported Webhook Events

You can retrieve data in JSON format. At the moment, webhooks are available for notification event, while we are working on supporting more events.

Events

Description

Event is sent whenever a new notification is generated for a customer

Event is sent whenever an update occurs to customer's profile

Creating an Endpoint for Webhooks

Your endpoint must be an HTTP webhook address that can correctly process event notifications as described. You must also implement to make sure webhook requests originate from Gameball.

Configuring Webhooks

You can configure a webhook using Gameball admin dashboard by following the below steps:

  1. From your Gameball admin, go to Admin Settings > Account Integration.

  2. In the Webhooks section, click Edit.

  3. Enter the URL on which you want to receive notifications.

Receiving a Webhook

After you register a webhook URL, Gameball issues an HTTP POST request to the URL specified every time that event occurs. The request's POST parameters contain JSON data relevant to the event that triggered the request.

Verifying Webhooks

To ensure the webhook request is from Gameball, verify the X-GB-Signature header. This signature is a SHA1 hash of the payload and your SecretKey. By comparing the computed hash with the signature header, you can confirm the request's authenticity.

Example Verification Code

Here’s how to verify a webhook signature using Node.js:

Example Verification:

const crypto = require("crypto");

function verifySignature(req) {
    const SECRET_KEY = process.env.SECRET_KEY;
    // Get the signature from the header
    const signature = req.headers["x-gb-signature"];
    if (!signature) return false;

    // Compute the signature using the payload and secret key
    const payload = JSON.stringify(req.body);
    const computedSignature = crypto
        .createHash("sha1")
        .update(payload + ":" + SECRET_KEY)
        .digest("hex");

    // Compare the signatures
    return computedSignature === signature;
}

Webhooks Retry Policy

The webhook retry policy governs the behavior of failed webhook deliveries and provides guidelines for handling such scenarios. When a webhook delivery fails, it is essential to have a well-defined retry policy to ensure successful delivery of the payload. In our case, Gameball handles webhooks behavior in case of sending failure as described below.

Failed Attempt

The webhook attempt is considered a failed attempt whenever Gameball receives a response with status code that is not 2XX, which means that for example, a status code of 403 is considered as a failed attempt, hence the retry policy applies.

Retry Attempts

The retry policy defines the number of attempts that will be made to deliver the webhook payload. Gameball provides three retry attempts. The retry policy also specifies the delay between each retry attempt. The delays durations are specified as follows, 1st attempt is after 5 minutes, the 2nd attempt is after 20 minutes and the final attempt is after 60 minutes. Lastly, if the webhook failed to send after all these attempts, this specific webhook request will be discarded.

configure a webhook subscription
verification
Notifications
Customer Profile Update