Webhooks

A webhook is a callback function that delivers an event payload to a URL when certain events occur in Nitro. The URL can be any address, including https, where you can access the files sent by Nitro. Typically, webhook data is used to develop processes not available in Nitro. For example, you could create a process that ingests the webhook data to send an email notification when a user receives a recognition.

You can trigger a webhook when the following events occur:

• Points earned - Data includes the user ID, point category, number of points, time when the points were awarded, and other event information.
• Mission completion - Data includes the earned user's ID and name, the completion timestamp, and the mission ID, name, display name, action phrase, point rewards and other mission information.
• Level earned - Data includes the earned user's ID and first and last name, the level name and description, if the user leveled up or down, and other information.
• Recognition given - Data includes the exchange ID and name, the giver's ID and name, the recipient's ID and name, the category ID and name, and other recognition information.

Create or Edit a Webhook

1. Open Nitro Studio > Integrate > Webhooks.
2. Click New. Or, to edit an existing webhook, click Edit ().
3. Set webhook properties:

Field	Description
Name	The webhook name.
Description	The webhook description.
Callback Url	The URL of the location where you want to receive the event payload.
Active	Select to activate the webhook.
Triggers	Select an event trigger. When an event occurs for the webhook type, an event payload will be sent to the Callback URL. Each point category can only be associated with one webhook. The available triggers are: User mission complete - send the payload when a user completes a mission. A payload will not be sent for group mission completions. User [point category name] earned - send the payload when a user earns points within this point category. [interaction name] interaction created - send the payload when a user gives a recognition within this recognition exchange. User level earned - send the payload when a user's level changes.

4. Click Save.
5. (Recommended) Add code to validate the authenticity of the request you receive from Nitro using the information in the Webhook URL Validation section.

Webhook Processing

A webhook eventId is unique to the payload event. If a webhook call fails (the HTTP status code returned to Nitro is not between 200 and 399), it's retried every 3 hours up to 3 days. The original and retry calls are identical in terms of payload, headers, etc.

When sending a response to Nitro after receiving a payload, the response should be sent as soon as the payload is received as the endpoint timeout is 30 seconds.

Webhook URL Validation

The event payload will be delivered in UTF-8 format via a POST call to the URL configured in the webhook.

Show me an example of the body of a points event post call

{
  "eventId": "<uuid - unique identifier assigned to the event>",
  "context": {
    "siteId": <siteId>,
    "apiKey": "<apiKey>",
    "ics": "<ics>"
  },
  "eventType": "USER_POINTS_EARNED",
  "data": {
    "pointCategory": {
      "id": <pointCategoryId>,
      "name": "<pointCategoryName>",
      "isDefault": <true/false - indicates if the point category is Nitro’s default point category>,
      "linkedToBankAccount": <true/false - indicates if the point category is associated to a BIW Award Account>
    },
    "user": {
      "id": <uuid - unique identifier assigned to the user>,
      "userId": "<gamification userId>",
      "firstName": "<user's firstName>",
      "lastName": "<user's lastName>"
    },
    "pointHistoryId": <pointsHistoryId>,
    "amount": <points awarded/ debited>,
    "creditBalanceAmountApplied": <number of points applied to the credit balance>,
    "debitBalanceAmountApplied": <number of points applied to the debit balance>,
    "lifetimeBalanceAmountApplied": <number of points applied to the lifetime points balance>,
    "description": "challenge:<challengeName>",
    "timestamp": <unix timestamp - the time when points were awarded>
  }
}

Show me an example of the body of a mission completion event post call

{
  "eventId": "<uuid - unique identifier assigned to the event>",
  "context": {
    "siteId": <siteId>,
    "apiKey": "<apiKey>",
    "ics": "<ics>"
  },
  "eventType": "USER_CHALLENGE_COMPLETE",
  "data": {
    "challenge": {
      "id": <challengeId>,
      "name": "<challengeName>",
      "displayName": "<challengeDisplayName>"
    },
    "user": {
      "id": <uuid - unique identifier assigned to the user>,
      "userId": "<gamification userId>",
      "firstName": "<user's firstName>",
      "lastName": "<user's lastName>"
    },
    "actions": [
      {
        "eventId": "<uuid - unique identifier assigned to the action event>",
        "name": "<actionName>",
        "passive": <true/false - indicates if this is a passive action>,
        "actionTime": <unix timestamp - the time when the action was logged>,
        "value": <actionValue>
      },
      {
        "eventId": "<uuid -unique identifier assigned to the action event>",
        "name": "<actionName>",
        "passive": <true/false - indicates if this is a passive action>,
        "actionTime": <unix timestamp - the time when the action was logged>,
        "value": <actionValue>
      }
    ],
    "userChallengeHistoryId": <userChallengeHistoryId>,
    "actionPhrase": "<the mission's action phrase>",
    "timestamp": <unix timestamp - the time when the mission was earned>,
    "pointRewards": [
      {
        "pointCategory": {
          "id": <pointCategoryId>,
          "name": "<pointCategoryName>"
        },
        "pointTransactionId": <uuid - unique identifier assigned to the point transaction event>,
        "amount": <number of points awarded>
      },
      {
        "pointCategory": {
          "id": <pointCategoryId>,
          "name": "<pointCategoryName>"
        },
        "pointTransactionId": <uuid - unique identifier assigned to the point transaction event>,
        "amount": <number of points awarded>
      }
    ]
  }
}

Show me an example of the body of a level earned event post call

{
  "eventId": "<uuid - unique identifier assigned to the event>",
  "context": {
    "siteId": <siteId>,
    "apiKey": "<apiKey>",
    "ics": "<ics>"
  },
  "eventType": "USER_LEVEL_EARNED",
  "data": {
    "user": {
      "id": <uuid - unique identifier assigned to the user>,
      "userId": "<gamification userId>",
      "firstName": "<user's firstName>",
      "lastName": "<user's lastName>"
    },
    "level": {
      "id": <levelId>,
      "name": "<level name>",
      "iconUrl": "<level image URL>",
      "description": "<level description>"
    },
    "userLevelHistoryId": <userLevelHistoryId>,
    "actionPhrase": "<level action phrase>",
    "timestamp": <unix timestamp - the time when the level change occurred>,
    "direction": "<UP or DOWN - indicates if the user's level increased or decreased"
  }
}

Show me an example of the body of a recognition event post call

{
  "eventId": "<uuid - unique identifier assigned to the event>",
  "context": {
    "siteId": <siteId>,
    "apiKey": "<apiKey>",
    "ics": "<ics>"
  },
  "eventType": "INTERACTION_CREATED",
  "data": {
    "id": <the recognition event Id>,
    "giver": {
      "id": <the giver userId>,
      "username": "<the giver's gamificationId>",
      "firstName": "<the giver's first name>",
      "lastName": "<the giver's last name>"
    },
    "exchange": {
      "id": <exchangeId>,
      "name": "<the exchange name>"
    },
    "category": {
      "id": <categoryId>,
      "name": "<the category name>"
    },
    "interactions": [
      {
        "recipient": {
          "id": <the recipient userId>,
          "username": "<the recipient's gamificationId>",
          "firstName": "<the recipient's first name>",
          "lastName": "<the recipient's last name>"
        },
        "value": <number of points awarded>,
        "recipientActionId": <the recipient actionId>,
        "giverActionId": <the giver actionId>,
        "recipientPointHistoryId": <the recipient pointHistoryId>,
        "giverPointHistoryId": <the giver pointHistoryId>
      },
      {
        "recipient": {
          "id": <the recipient userId>,
          "username": "<the recipient's gamificationId>",
          "firstName": "<the recipient's first name>",
          "lastName": "<the recipient's last name>"
        },
        "value": <number of points awarded>,
        "recipientActionId": <the recipient actionId>,
        "giverActionId": <the giver actionId>,
        "recipientPointHistoryId": <the recipient pointHistoryId>,
        "giverPointHistoryId": <the giver pointHistoryId>
      }
    ],
    "interactionDate": <unix timestamp - the time when the recognition was sent>,
    "comment": "<the giver's comment>"
  }
}

Once you define the URL, you can validate the authenticity of the request from Nitro. The following authorization headers are provided in the http call:

• Authorization - SHA256 Signature=<authorization signed hash>
• x-bb-content-sha256 - The event in the body, hashed into a sha256 string
• x-bb-date - A UNIX timestamp generated at the moment the event was sent

You will need your site's secret key to complete the following verification steps. The secret key is available in Nitro Studio > Configuration > Site Settings > Overview > API secret key.

1. Concatenate the following strings into one.

<your site's secret key> "|" <x-bb-content-sha256 header value> "|"<x-bb-date header value>

2. Convert the string from Step 1 into a SHA256 hash. The hash must be 64 characters long. If your hash is shorter than 64 characters, prefix the hash with zeros to make it 64 characters.

<your language of choice string to sha256 converter>(<string from step 1>)

3. Compare the hash produced in Step 2, with the hash in the Authorization header (with the “SHA256 Signature=” prefix removed).

<hash from step 2> == <authorization signed hash - without the “SHA256 Signature=” part from the Authorization header>

4. Convert the entire event body payload received into a SHA256 hash. The hash must be 64 characters long. If your hash is shorter than 64 characters, prefix the hash with zeros to make it 64 characters.

Ensure the hash contains the raw payload and with no formatting applied to the data. Formatting may cause you to lose the numeric precision that the original content was generated with.

<your language of choice string to sha256 converter>(<event body received>)

5. Compare the hash produced in Step 4 with the hash received in the x-bb-content-sha256 header.

<hash from step 4> == <x-bb-content-sha256>

If the comparisons in Step 3 and Step 5 pass, your payload is guaranteed to originate from Nitro.

Show me example code I can modify to use for validation

public class SignatureValidator {
  public final static String HEADER_PAYLOAD_HASH = "x-bb-content-sha256";>
  public final static String HEADER_TIMESTAMP = "x-bb-date";
  public final static String HEADER_AUTH = "Authorization";
  public final static String HEADER_AUTH_PRE = "SHA256 Signature=";
                
  String secretKey = Site.getSecretKey();
                
  public void validateSignature(Request request){
  //Ensure this is the raw payload with no formatting applied to it.
    String payload = request.getPayload();
    String payloadHash = request.getHeader(HEADER_PAYLOAD_HASH);
    String timestamp = request.getHeader(HEADER_TIMESTAMP);
    String signature = request.getHeader(HEADER_AUTH).substring(HEADER_AUTH_PRE.length);
                
    if (!payloadHash.equals(generatePayloadHash(payload))) {
        throw new Exception("Invalid Payload");
    }
    if (!signature.equals(generateSignature(secretKey, payloadHash, timestamp) {
        throw new Exception("Invalid Signature");
    }
  }
                
  private String generateSignature(String secretKey, String payloadHash, String timestamp){
    return Hash.generateSHA256Hex( secretKey + "|" + payloadHash + "|" + timestamp);
  }
  private String generatePayloadHash(String payload) {
    return Hash.generateSHA256Hex(payload);
  }
}

See also

Point categories

Missions

Levels

Recognition