Webhooks

If you need to send a request to your API server when the conditions of a quest are met, you can configure an optional "Webhook" parameter for each quest.

info

You can define an unlimited number of Webhooks to be sent.

Webhook Configuration

To configure webhooks, you need to fill in the "Integration" section on the quest editing or creation page.

This section consists of multiple Metadata fields and Webhook fields.

The Metadata field is used to pass Metadata key and Metadata value in the request that you can configure.

In the Webhook field, you can add a link to which the webhook needs to be sent.

Webhook JSON description

If an event meets the conditions specified in the "Triggers" section of the quest creation/editing form, the quest system sends a webhook to all the URLs specified in the "Integration" section.

• quest: The quest object contains information about the quest.
  • id (string): The ID of the quest.
  • projectId (string): The ID of the project the quest belongs to.
  • name (string): The name of the quest.
  • shortDescription (string): A short description of the quest.
  • description (string): The full description of the quest.
  • logo (string): The URL of the quest's logo image.
  • sprite (string): The URL of the quest's sprite image.
  • difficulty (string): The difficulty level of the quest. Variants: easy | mediaum | hard
  • visibility (string): The visibility setting of the quest. Variants: public | hidden
  • completionsLimit (number): The limit of quest completions.
  • startDate (string): The start date of the quest in ISO 8601 format.
  • endDate (string): The end date of the quest in ISO 8601 format. Can be null if the quest has no end date.
  • availableRegions (null or array): IDs of countries where the quest is available. Can be null if the quest is available in all regions.
  • isDraft (boolean): Indicates whether the quest is a draft or not. Example: false
  • trigger (object): The trigger configuration for the quest.
    • logicalOperator (string): The logical operator used for multiple conditions. Variants: AND | OR
    • conditions (array): An array of conditions for the trigger.
      • id (string): The ID of the condition.
      • title (string): The title of the condition.
      • eventName (string): The name of the event associated with the condition.
      • hasBeenPerformed (boolean): Indicates whether the event has been performed or not.
      • amount (number): The amount associated with the condition.
      • within (number): The time frame within which the condition must be met.
      • rangeType (string): The type of range for the condition. Variants: ever | within_last
      • range (string): The range for the condition. Variants: weeks | months | years
  • rewards (array): An array of rewards for completing the quest.
    • id (string): The ID of the reward.
    • rewardId (string): The ID of the specific reward.
    • quantity (number): The quantity of the reward.
    • claimType (string): The type of claim for the reward. Variants: AUTO | MANUAL
    • rewardType (string): The type of the reward. Variants: VIRTUAL_ITEM | VIRTUAL_CURRENCY
  • createdAt (string): The creation date of the quest in ISO 8601 format.
  • updatedAt (string): The last updated date of the quest in ISO 8601 format.
  • status (string): The status of the quest. Variants: active | finished
• userId (string): The ID of the user.
• metadata (object): Custom metadata parameters.
  • custom_key_1 (string): User defined metadata key and value.
• rewards (array): An array of rewards and their status.
  • rewardId (string): The ID of the reward.
  • status (string): The status of the reward. Variants: manual_claim | claim | error
  • errorMessage (string, optional): The error message associated with the reward. Example: "[0401-4001]: Could not find item for project 216989 with id VL-011 ()"

The Webhook JSON example

{
  "quest": {
    "id": "a63594f4-be8e-40e4-9f31-8e9d72a25854",
    "projectId": "1a298a72-b5c9-4460-a921-8e35203b5014",
    "name": "event quest",
    "shortDescription": "test quest for event",
    "description": "full description",
    "logo": "https://example.com/ffff-ffff-ffff-ffff.jpg",
    "sprite": "https://example.com/ffff-ffff-ffff-ffff.jpg",
    "difficulty": "easy",
    "visibility": "public",
    "completionsLimit": 1,
    "startDate": "2023-05-14T00:00:00.000Z",
    "endDate": null,
    "availableRegions": null,
    "isDraft": false,
    "trigger": {
      "logicalOperator": "AND",
      "conditions": [
        {
          "id": "53150a89-35e6-47d8-9c5a-261dcbcb820c",
          "title": "EDIT_ARTICLE",
          "eventName": "EDIT_ARTICLE",
          "hasBeenPerformed": true,
          "amount": 7,
          "within": 7,
          "rangeType": "ever",
          "range": "days"
        }
      ]
    },
    "rewards": [
      {
        "id": "b09f6a4f-9001-4e2b-948a-6594a247df67",
        "rewardId": "one-more-sword-112",
        "quantity": 1,
        "claimType": "MANUAL",
        "rewardType": "VIRTUAL_ITEM"
      },
      {
        "id": "368091d1-2aa0-4058-af04-422b6527a6c4",
        "rewardId": "VL-011",
        "quantity": 1,
        "claimType": "AUTO",
        "rewardType": "VIRTUAL_CURRENCY"
      }
    ],
    "createdAt": "2023-05-18T14:34:26.921Z",
    "updatedAt": "2023-05-19T10:19:48.315Z",
    "status": "active"
  },
  "userId": "7896-6548-87as-6549",
  "metadata": {
    "custom_key_1": "custom_value",
    "custom_key_2": "custom_value"
  },
  "rewards": [
    {
      "rewardId": "one-more-sword-112",
      "status": "manual_claim"
    },
    {
      "rewardId": "VL-011",
      "status": "error",
      "errorMessage": "[0401-4001]: Could not find item for project 216989 with id VL-011 ()"
    }
  ]
}