Build your Own Notification System

Notifications are a powerful way to build stronger relationships with your customers by keeping them engaged with your service.

Gameball provides default notification options, such as:

• In-app notifications for web applications.

• Push notifications using Firebase for mobile apps.

But what if you have your own notification system, like SMS messaging, a WhatsApp bot, or third-party services like Amazon SNS, or Twilio?

Gameball makes this easy by using webhooks to notify your system whenever a notification needs to be sent.

How It Works

• Your Webhook Endpoint: A piece of code on your server (written in any language like Ruby, PHP, or Node.js) that processes incoming requests.

• Providing the URL: Share your endpoint URL (e.g., https://yourdomain.com/webhook-endpoint) with Gameball.

• Receiving Notifications: Gameball sends a POST request with all the necessary data to your endpoint whenever a customer should receive a notification.

By integrating webhooks, you can seamlessly use your notification systems to keep customers informed and engaged.

👉 Learn more about Webhooks

This tutorial will guide you through the steps to integrate Gameball notification webhooks with your own system.

Steps to Get Started

1. Build a webhook endpoint on your server to receive notifications.

2. Subscribe to notification webhooks from your Gameball dashboard.

3. Verify webhook signatures to ensure secure communication.

4. Create logic to send notifications to your customers via your preferred channels.

Note: Code snippets provided in this tutorial are for illustration purposes and may require adjustments to work in your environment.

Example Scenario

Imagine you own a store that specializes in video games and gift cards. You want to send notifications to your customers through your own channels, such as SMS, WhatsApp, or other custom platforms. This tutorial will help you achieve that integration.

---

Configurations

Before diving in, you need to set up some configurations to enable webhooks.

Step 1: Build a Notifications Endpoint

The first step is to prepare a webhook endpoint on your server where Gameball will send POST requests containing notification details. This endpoint will act as the bridge between Gameball and your notification system.

app.post('/gb-webhook/notification', (request, response) => {

});

The above function will be invoked when a POST request is sent to /gb-webhook/notification.

Step 2: Activate Notifications Webhook

In your Gameball dashboard, navigate to Admin Settings > Account Integration > Webhooks and add your notification endpoint URL (www.yourdomain.com/gb-webhook/notification in this example) to Notification Webhook.

Configuring Webhooks

and then click Update Webhook. Now, a POST request will be sent to your endpoint every time a notification is to be sent to your customer.

Step 3: Verifying Webhooks

You should verify that the incoming request is a legit request from Gameball and not a malicious request that tries to spam your system. You can achieve this by calculating a digital signature which is SHA1 hash in X-GB-Signature header. You can get more information about webhook verification in this section.

const crypto = require("crypto");

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

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

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

app.post('/gb-webhook/notification',(request,response) => {
    // verify the request
    if(verifySignature(request) == false) return; // malicious request
});

Step 4: Write Your Own Logic

In the webhook request body, you will get all the needed data for you to send your customized notifications designated customers. Each notification item in the posted data will contain the customer_id and locales with their titles and bodies. You can check the full data specification and example in the documentation here.

Here is an example of a notification data:

{
  "event": "customer.notification.push",
  "client_id": "2155",
  "customer_id": "webhook-test",
  "gb_customer_id": 1234,
  "created_at": "2024-11-12T19:02:24.631Z",
  "data": [
    {
      "local": "en",
      "icon": "https://example.com/image.webp",
      "body": "Your recent activities have been amazing! Keep up the great work and enjoy your rewards!",
      "title": "Well Done!"
    }
  ]
}

After receiving the notification, you can process it according to your preferences and you should have the flexibility of building whatever logic you need.

The below example demonstrates how SMS integration can be done with notification webhooks. Once a notification event is received, you will find the customer_id in the request body. You can use the received customer_id to retrieve your customer's mobile number or any other required data from your database, then use an SMS Gateway to send an SMS to your customer.

app.post('/gb-webhook/notification',(request,response) => {
    // verify the request
    if(verifySignature(request) == false) return; // malicious request

    let webhookData = request.body;
    let customerId = webhookData.customer_id;
    /* Example: {userId:"14415233", username:"XxGamerxX", phone: "[phone]", deviceToken: "dSvsjGMuQ5GwcAYPAqu4PW:APA91bFzRjdiTj" } */
    let customerInfo = getCustomerDetails(customerId);
    // sends an SMS to your customer's phone number
    SMSGateway.sendMessage({
        phoneNumber: customerInfo.phone,
        messageTitle: webhookData.data[0].title,
        messageContent: webhookData.data[0].body
    });
});

And now your customers should receive an SMS message when they get a notification from Gameball.

Whatsapp Example

The next day your boss requested a slight change, that you need to also send WhatsApp messages to your customers in addition to sending SMS.

You will need to have an integration with WhatsApp business API or any communication API as Twilio.

In your “/gb-webhook/notification” endpoint you will add the logic that sends WhatsApp message to your customer.

app.post('/gb-webhook/notification',(request,response) => {
    // verify the request
    if(verifySignature(request) == false) return; // malicious request

    let webhookData = request.body;
    let customerId = webhookData.customer_id;
    /* Example: {userId:"14415233", username:"XxGamerxX", phone: "[phone]", deviceToken: "dSvsjGMuQ5GwcAYPAqu4PW:APA91bFzRjdiTj" } */
    let customerInfo = getCustomerDetails(customerId);
    // sends an SMS to your customer's phone number
    SMSGateway.sendMessage({
        phoneNumber: customerInfo.phone,
        messageContent: webhookData.data[0].body
    });

    // sends a Whatsapp message to your customer
    WhatsappHandler.sendWhatsappMessage({
        phoneNumber: customerInfo.phone,
        messageContent: webhookData.data[0].body
    })
});

In addition to SMS and Whatsapp you are asked to send push notifications to your customer's mobile devices as push notifications. There are some services that provide this service, we will use AWS SNS for this example.

Push Notification

AWS SNS uses device tokens to identify mobile devices. You store each customer's device token in your database.

In your “/gb-webhook/notification” endpoint you will add the logic that sends push notification to your customer mobile device.

app.post('/gb-webhook/notification',(request,response) => {
    // verify the request
    if(verifySignature(request) == false) return; // malicious request

    let webhookData = request.body;
    let customerId = webhookData.customer_id;
    /* Example: {userId:"14415233", username:"XxGamerxX", phone: "[phone]", deviceToken: "dSvsjGMuQ5GwcAYPAqu4PW:APA91bFzRjdiTj" } */
    let customerInfo = getCustomerDetails(customerId);
    // sends an SMS to your customer's phone number
    SMSGateway.sendMessage({
        phoneNumber: customerInfo.phone,
        messageContent: webhookData.data[0].body
    });

    // sends a Whatsapp message to your customer
    WhatsappHandler.sendWhatsappMessage({
        phoneNumber: customerInfo.phone,
        messageContent: webhookData.data[0].body
    });
    
    // sends a push notification
    SNS.sendNotification({
        token: customerInfo.deviceToken,
        title: webhookData.data[0].title,
        body: webhookData.data[0].body
    });
});

By the end of this tutorial you should now be able to implement your own notification system using notifications hooks.