Live Notifications through Webhooks

Live Notifications through Webhooks

Webhooks allow you to receive real-time notifications about important events through HTTP requests. This guide explains how to add a webhook, configure authentication, and understand the notification format.

Adding a Webhook

You can easily add a Webhook by following these steps:
  1. Log in to your SecureFlag Admin account.
  2. Go to Management Portal and select Details to view your organization configuration.
  3. Click on the drop down Live Notifications option and select Manage Destinations under Destinations Settings.
  4. Under the Webhook option add the  Webhook URL where you want to receive event notifications and give it a label.



Provide an Authentication Token (Optional)

If an authentication token is supplied, it will be included in the header of every webhook request as:
Authorization: <AUTH_TOKEN>

Select The Event(s) You Want to Subscribe to

  1. Log in to your SecureFlag account.
  2. Go to Management Portal and select Details under your organization.
  3. Click on Live Notifications option and select Manage Events under Events Settings.
  4. Here you can select the Webhook you want to get notified.
  5. Once done, click Save to save the notification events.

Notes
 Note: For each event, you can configure up to one Webhook.



Webhook Notifications and Event Format

All webhook requests are sent using a consistent JSON structure. Each request contains a list of messages, with each message including:
  1. msg: The actual event information, JSON-encoded.
  2. msg_type: Always "text".
  3. aud: Defines the audience — can be either "global" for group notifications or a specific "user_email" for personal notifications.

Webhook Payload Format

{
  "messages": [
    {
      "msg": "${json_encoded_message}",
      "msg_type": "text",
      "aud": [
        "global"
      ]
    }
  ]
}

Audience Types

  1. Global: Sends the message to all users.
  2. Specific Users: Sends the message to selected user email addresses.

Examples

Global Notification Example

{
  "messages": [
    {
      "msg": "{\"event\": \"SECURE_CODING_MONTH_RUNNING\", \"1\": \"John Smith - [Team: BackEnd Developers]\", \"2\": \"Jane Doe - [Team: QA Engineers]\", \"3\": \"Frank Green - [Team: FrontEnd Developers]\"}",
      "msg_type": "text",
      "aud": [
        "global"
      ]
    }
  ]
}

This sends a group notification about the ongoing "Secure Coding Month" event.

Personal Notification Example

{
  "messages": [
    {
      "msg": "{\"event\": \"TRIVIA_QUIZ\", \"idTrivia\": \"100\", \"title\": \"Quiz #1\", \"question\": \"What's the capital of Italy?\", \"answer1\": \"Rome\", \"answer2\": \"Milan\", \"answer3\": \"Naples\", \"answer4\": \"Turin\", \"correctAnswer\": \"1\"}",
      "msg_type": "text",
      "aud": [
        "user1@secureflag.com",
        "user2@secureflag.com"
      ]
    }
  ]
}

This sends a trivia quiz notification specifically to two selected users.

Webhook Events Reference

NEW_CONTENT

Description:
Notifies the group about newly available learning content, features, or announcements.

Payload Example:
{
  "event": "NEW_CONTENT",
  "title": "${title}",
  "description": "${description}",
  "textUrl": "${textUrl}",
  "url": "${url}"
}

  1. title: Title of the new content or announcement
  2. description: A short summary of the content
  3. textUrl / url: Links to learn more or access the content

TRIVIA_QUIZ

Description:
Sends a weekly multiple-choice trivia quiz directly to all users.

Payload Example:
{
  "event": "TRIVIA_QUIZ",
  "idTrivia": "${idTrivia}",
  "title": "${title}",
  "question": "${question}",
  "answer1": "${answer1}",
  "answer2": "${answer2}",
  "answer3": "${answer3}",
  "answer4": "${answer4}",
  "correctAnswer": "${correctAnswer}"
}

Used to engage users with educational and fun content via direct message.

TOURNAMENT_SCHEDULED

Description:
Reminds users of an upcoming tournament. Sent both to the group and as a personal notification.

Payload Example:
{
  "event": "TOURNAMENT_SCHEDULED",
  "name": "${name}",
  "countdownDays": "${days}"
}

  1. name: Tournament name
  2. countdownDays: Days remaining until the tournament starts

TOURNAMENT_RUNNING

Description:
Alerts users that a tournament is now live. Sent to both the group and users directly.

Payload Example:
{
  "event": "TOURNAMENT_RUNNING"
}

TOURNAMENT_ENDED

Description:
Notifies the group that the tournament has concluded.

Payload Example:
{
  "event": "TOURNAMENT_ENDED"
}

SECURE_CODING_MONTH_RUNNING

Description:
Announces the active status of Secure Coding Month, showcasing top participants. Sent to the group.

Payload Example:
{
  "event": "SECURE_CODING_MONTH_RUNNING",
  "users": {
    "1": "${name} - [Team: ${team_name}]",
    "2": "${name}",
    "3": "${name} - [Team: ${team_name}]"
  }
}

Highlights up to 3 top-performing users with their teams if any.

SECURE_CODING_MONTH_ENDED

Description:
Informs the group that Secure Coding Month has concluded.

Payload Example:
{
  "event": "SECURE_CODING_MONTH_ENDED"
}

USER_NEW_ACHIEVEMENT

Description:
Sent as a personal message when a user earns a certificate or trophy for completing a learning path or achieving a milestone.

Payload Example:
{
  "event": "USER_NEW_ACHIEVEMENT",
  "name": "${name}",
  "type": "CERTIFICATION | TROPHY"
}

USER_CURRENT_POSITION

Description:
A direct message alerting a user of their position in the Global Leaderboard, if they rank within the top 5000.

Payload Example:
{
  "event": "USER_CURRENT_POSITION",
  "position": "${position}",
  "url": "${url}"
}

  1. url: Link to view the leaderboard or detailed stats

ORG_TOP_100_USERS

Description:
Broadcasts a group notification listing members of the organization who are in the top 100 of the global ranking.

Payload Example:
{
  "event": "ORG_TOP_100_USERS",
  "users": {
    "${position}": "${name}",
    "${position}": "${name}"
  }
}

ORG_TEAMS_STATUS

Description:
Notifies the group of the current top-performing internal teams, based on average points. Displays up to 3 teams.

Payload Example:
{
  "event": "ORG_TEAMS_STATUS",
  "teams": {
    "${team_name}": "${avg_points}",
    "${team_name}": "${avg_points}",
    "${team_name}": "${avg_points}"
  }
}

USER_ASSIGNED_ACTIVITY_STATUS

Description:
A direct message reminder for users about their assigned activities — highlighting any that are incomplete or expired.

Payload Example:
{
  "event": "USER_ASSIGNED_ACTIVITY_STATUS",
  "incomplete": [
    "${activity_name}",
    "${activity_name}"
  ],
  "expired": [
    "${activity_name}",
    "${activity_name}"
  ]
}