Webhooks

What Are Webhooks?

Webhooks enable you to subscribe to events within a software system and automatically receive data deliveries to your server as these events occur.

Unlike polling an API at regular intervals to check for updates, webhooks deliver data in real-time. You only need to set up a webhook once, specifying the events of interest.

How Do Webhooks Work?

When you configure a webhook, you designate a URL to receive HTTP requests. Any subscribed event that occurs within our system triggers an immediate HTTP request to your specified URL. If your server is configured correctly, it can process or act based on the incoming data.

Available Events

As previously mentioned, each webhook is connected to a specific event. A webhook is sent in response to the occurrence of an event. Detailed information about available events and their types is provided in the Introduction to Events section.

How to Create a Webhook

Before linking a webhook to an event, first create the webhook on your side and obtain its URL.

Webhook Structure

• Trigger Conditions: Specify the events and filters that initiate the webhook.
• Configurations: Includes the webhook URL and authentication headers.
• Custom Description: Allows you to provide a detailed explanation of what the webhook does and its purpose.

To understand the data that is posted to a webhook, it's crucial to grasp the structure of the event object that gets delivered. Each object transmitted encapsulates all the necessary information about the event that triggered the webhook.

What Data Structures Are Sent via Webhooks?

When an event triggers a webhook in your system, it sends a structured payload containing all relevant data about the event. Understanding these data structures is key to efficiently processing and responding to the information your system receives. Below, we detail the common format of these payloads and give examples of how data may differ based on the event type.

General Payload Structure

Every webhook payload follows a standardized format designed to ensure that you can easily parse and utilize the data sent. Here is the typical structure of a webhook payload:

• namespace: String identifying the source of the event
• dataType: Type of event being transmitted
• userId: Unique identifier for the user involved in the event
• body: Contains the specific data pertaining to the event
• eventId: Unique identifier for the specific event
• externalId: An external identifier that links to other relevant systems

This structure is adaptable depending on the type of event, providing the flexibility to include various kinds of information within the body.

Event-Specific Body Structures

Custom Events:

The payload contains the details of the custom event directly within the body. The body will reflect the properties specific to the event.

Internal events

Each event type in a system triggers a distinct data structure, specifically designed to efficiently convey all the necessary details. Here are some examples illustrating how these structures can vary between different event types:

// DAILY_CLAIMED
{
  "rewards": {..}
}

// LEVEL_UP
{
  "fromLevel": 2,
  "toLevel": 3,
  "completedLevels": [2],
  "direction": "up",
  "tokensSpent": 0.05
}

// Quest-related
{
  "target": {
    "challenges": [...],
    "user": {...},
    "rewardBundle": {
      "rewards": [...]
    }
  },
  "rewards": [...] // Only for QUEST_CLAIMED
}

// REDEEM_TRANSACTION_COMPLETED
{
  "tokens": 100
}

Scheduled Events

• year: Current year.
• month: Current month.
• day: Current day.
• hour: Current hour.
• dayOfYear: Day number of the year.
• unixTimestamp: Timestamp in milliseconds.
• dayOfWeek: Day of the week.
• weekOfYear: Week number of the year.
• timezone: Timezone offset as a string.

Property-based events

Reflects updates to properties with detailed value information:

• value: Current property value.
• previousValue: Previous property value before the update.
• new: Boolean indicating if the previous value was 'null'.

Admin events

Admin events are triggered by actions performed by administrators on a dashboard. These events extend the default event structure and include the following body parameters:

• method: The HTTP method (e.g., POST, GET) used in the admin action.
• namespace: The relevant API scope or resource affected by the action.
• auth: The authorization type, set to ADMIN_ACCESS, indicating restricted access to admin-level users.
• query: The query string parameters included in the URL, used to filter or modify the request.
• params: The route parameters, typically used to specify resource identifiers in the URL path (e.g., /resource/:id).
• body: The entity-specific object containing all relevant data for the action, such as entity properties or modifications.

📘

The list of available events and the structure of the body are still in development and may change. Please consult with the development team before using admin events in production to ensure accuracy