r4nkt
  • Introduction
  • Getting Started
  • Concepts
    • Overview
    • Achievements
    • Actions
    • Activities
    • Badges
    • Criteria
    • Criteria Conditions
    • Criteria Groups
    • Custom Data Reference
    • Games
    • Leaderboards
    • Players
    • Rewards
    • Scores
  • Cookbook
    • Criteria Conditions
    • Achievements
  • API
    • Overview
    • Authentication
    • Achievements
    • Actions
    • Activities
    • Criteria
    • Criteria Groups
    • Leaderboards
    • Players
    • Player Badges
    • Rewards
    • Scores
  • Webhooks
    • Overview
    • Getting Started
    • Events
  • PHP SDK
    • Overview
    • Getting Started
  • Laravel Package
    • Overview
    • Installation
    • Webhooks
Powered by GitBook
On this page
  • How they work
  • Configuration
  • Authentication
  • Retries
  • Authentication and Signing

Was this helpful?

  1. Webhooks

Getting Started

How they work

There are certain events that will occur that you may find interesting. Whenever one of these takes place, we will pass that information along to you. Probably the most interesting event is whenever a player has been awarded a badge. When this happens, you will be notified via webhook of the event along with relevant information, eg. the player and the achievement that was earned and any related rewards.

At this point, you can do whatever you want or need to do with the information. Typically, you will then notify the player that they have been awarded a badge. You may also want to handle any associated rewards.

The webhook itself works by firing a POST request to the game's webhook URL property. The request's payload will have all of the event's relevant data. For details about the payloads, please look at the documentation for each event.

Configuration

Your game's webhook settings can be configured and tested in the game dashboard's webhook settings panel. It consists of two settings:

  • Webhook URL: This is the URL that will be called to pass information along to you for different events. A new game has no webhook URL. You must set this manually.

  • Webhook secret: This secret is used to validate any webhook calls you receive. A random secret is generated for all new games, but you can always change it to something more preferable.

A game requires neither a webhook URL nor a webhook secret, but no webhook calls will be made unless they are both provided.

Once your game has a valid webhook URL and webhook secret, then the webhook will be called for each event we fire.

Be sure to take advantage of the "test webhook" functionality that you can find in the game dashboard's webhook settings panel.

Authentication

The webhooks that we send will be signed by the webhook secret, which you should have provided during game creation or modification.

While you don't have to validate incoming webhook requests, we highly recommend that you do so.

Retries

If we send a webhook and receive a 2xx status code, then we will consider the webhook successful. If, however, any other status code is returned or if no response is made within 3 seconds, then we will consider the webhook failed.

Failed webhooks will be retried a maximum of 3 times. Prior to each retry, we will wait a small-but-increasing period of time: 10 seconds before the first retry, 100 seconds before the second, and 1000 seconds before the third and final.

If all retries have failed, then that particular event will not be sent again.

Authentication and Signing

$signature = hash_hmac('sha256', $payload, $secret);

$payload is the JSON-formatted body of the POST request for the specific event.

$secret is your game's webhook secret setting.

The $signature value that is generated must match the value passed in the X-R4nkt-Signature header. If it does not, then the webhook is not valid.

Please note that the signature is not encoded, Base64 or otherwise.

PreviousOverviewNextEvents

Last updated 3 years ago

Was this helpful?

Each time we make a webhook call, we pass a header called X-R4nkt-Signature, which will contain a signature that your webhook handler can use to validate the incoming request. The signature is generated using the method, like so:

hash_hmac() function is a that is used to "[g]enerate a keyed hash value using the HMAC method".

The sample code above that is used to determine the signature is in PHP, but this can be done in many languages. Here are .

HMAC-256
PHP function
some examples