Notifications play a huge role in strengthening the bond between you and your customers (a.k.a. players) as it helps them remain engaged with your service.

Gameball offers you some default ways for sending notifications to your players such as having in-app notifications for web applications, and push notifications by integrating with firebase for mobile applications.

But what if you have your own notification system that you use to contact your players. Maybe an SMS messaging system or a WhatsApp bot you own or any other services you use for this purpose such as firebase messaging, Amazon SNS or Twilio.

Gameball uses webhooks to notify your application when an event happens and a notification is needed to be delivered to your player.

The webhook endpoint is just more code on your server, which could be written in Ruby, PHP, Node.js, or whatever you use. The webhook endpoint has an associated URL (e.g., https://yourdomain.com/webhookEndPoint ).

You will provide Gameball with your endpoint URL and whenever a player should receive a notification, a POST request will be sent to your endpoint with required data in the request body.

In this tutorial we will walkthrough how to set up your own notification system with Gameball.

To begin using notification webhooks with Gameball you should follow these steps:

1. Build a notification webhook endpoint on your server.

2. Subscribe to the notification webhook in your dashboard.

3. Verify the webhook signature.

4. Build your own logic for sending notifications to your player.

Let's assume that you own a store that excels in selling video games and gift cards for gamers all over the world. You want to send notifications to your players via your own notification channels that you use to communicate with your players.

Configurations

There are some configuration steps that you need to do to set up your way for having webhooks.

Step 1: Build Notifications Endpoint On Your Server

First of all, you will need to prepare an endpoint on your server that Gameball notification webhook will POST generated notifications to.

app.post('/GameballHooks/notification', (request, response) => {
​
});

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

Step 2: Activate Notifications Webhook

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

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 player.

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 BASE64 encoded in X-GB-Signature header. You can get more information about webhook verification in this section.

app.post('/GameballHooks/notification',(request,response) => {
    // verify the request
    if(verifyWebhook(request) == false) return; // malicious request
});

Build Your Own Logic

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 players. Each notification item in the posted data will contain the playerUniqueId 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:

{
   "notifications":[
      {
         "notificationId" : "123",
         "title": "New level!",
         "body": "Keep it up! You are now on Bronze ",
         "isRead": true,
         "createdAt": "2021-05-12T00:08:09.646174",
         "lang": "en",
         "icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb-icon-level-13.png"
      }
   ]
   ...
 }

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 playerUniqueId in the request body. You can use the received playerUniqueId it to retrieve your player's mobile number or any other required data from your database, then use an SMS Gateway to send an SMS to your player.

app.post('/GameballHooks/notification',(request,response) => {
    // verify the request
    if(verifyWebhook(request) == false) return; // malicious request
​
    let notificationData = request.body;
​
    /* Example: {userId:"14415233", username:"XxGamerxX", phone: "+20123456789", deviceToken: "dSvsjGMuQ5GwcAYPAqu4PW:APA91bFzRjdiTj" } */
    let playerData = getPlayerData(notificationData.playerUniqueId);
    
    // sends an SMS to your player's phone number
    SMSGateway.sendMessage({
        phoneNumber: playerData.phone,
        messageTitle: notificationData.notifications[0].title,
        messageContent: notificationData.notifications[0].body
    });
});

And now your players 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 players in addition to sending SMSes.

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

In your “/GameballHooks/notification” endpoint you will add the logic that sends WhatsApp message to your player.

app.post('/GameballHooks/notification',(request,response) => {
    // verify the request
    if(verifyWebhook(request) == false) return; // malicious request
​
    let notificationData = request.body;
​
    /* Example: {userId:"14415233", username:"XxGamerxX", phone: "+20123456789", deviceToken: "dSvsjGMuQ5GwcAYPAqu4PW:APA91bFzRjdiTj" } */
    let playerData = getPlayerData(notificationData.playerUniqueId);
   
    // sends an SMS to your player's phone number
    SMSGateway.sendMessage({
        phoneNumber: playerData.phone,
        messageTitle: notificationData.notifications[0].title,
        messageContent: notificationData.notifications[0].body
    });
​
    // sends a Whatsapp message to your player
    WhatsappHandler.sendWhatsappMessage({
        phoneNumber: playerData.phone,
        messageContent: notificationData.notifications[0].body
    })
});

​

​

AWS SNS Push Notification Example

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

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

In your “/GameballHooks/notification” endpoint you will add the logic that sends push notification to your player mobile device.

app.post('/GameballHooks/notification',(request,response) => {
    // verify the request
    if(verifyWebhook(request) == false) return; // malicious request
​
    let notificationData = request.body;
​
    /* Example: {userId:"14415233", username:"XxGamerxX", phone: "+20123456789", deviceToken: "dSvsjGMuQ5GwcAYPAqu4PW:APA91bFzRjdiTj" } */
    let playerData = getPlayerData(notificationData.playerUniqueId);
   
    // sends an SMS to your player's phone number
    SMSGateway.sendMessage({
        phoneNumber: playerData.phone,
        messageTitle: notificationData.notifications[0].title,
        messageContent: notificationData.notifications[0].body
    });
​
    // sends a Whatsapp message to your player
    WhatsappHandler.sendWhatsappMessage({
        phoneNumber: playerData.phone,
        messageContent: notificationData.notifications[0].body
    })
​
    // sends a push notification
    SNS.sendNotification({
        token: playerData.deviceToken,
        title: notificationData.notifications[0].title,
        body: notificationData.notifications[0].body
    })
});

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