Set up webhooks

Step-by-step guide on registering, configuring, and testing webhooks in claimr.

Register and configure webhooks in claimr

To receive real-time updates from claimr, you first need to register a webhook. This involves providing claimr with the URL of your endpoint (where you want to receive the data) and defining the scope of events you're interested in.

You can register a webhook through the claimr API documentation in Swagger.

1. Access webhooks section: Navigate to the webhooks section within the claimr API documentation in Swagger.

2. Set up POST request: You'll typically use a POST request to register a new webhook.

3. Define request body: In the request body, you'll provide the following information:

   • scope: Specify the type of events you want to receive updates for (e.g., user_activity).

   • url: Provide the URL of your endpoint.

   • secret (optional): Include a secret key for added security.

   • hook_id (optional): Assign a unique ID to your webhook for easy identification.

Request body example

JSON
{
  "scope": "user_activity",
  "url": "https://your-endpoint-url.com",
  "secret": "your-secret-key",
  "hook_id": "your-webhook-id" 
}

Benefits of secret keys

By utilizing secret keys, claimr provides a robust mechanism to ensure that your webhook communications are secure and reliable.

• Data Integrity: Ensures that the data received in webhook notifications has not been modified or corrupted during transmission.

• Authentication: Verifies that the webhook message originated from claimr and not from a malicious actor.

• Security: Adds an extra layer of security to your webhook integration, protecting your campaign data from unauthorized manipulation.

Secret key example

const payload = JSON.stringify(data);
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');

...

'x-claimr-signature': signature

Real-time activity tracking

Once you've set up a webhook, claimr will instantly send updates to your endpoint whenever a relevant event occurs within your campaigns. This allows your application to track user activity in real-time and respond accordingly.

Example scenario

Let's say a user logs in to your campaign and starts completing tasks. As the user interacts with your campaign (e.g., completes a "reCAPTCHA" task), claimr will immediately send a webhook notification to your endpoint with detailed information about the user's activity.

Webhook payload

The webhook payload will contain a wealth of information, including:

• A unique ID for the action ("id": "lisjywHXKAq6yQe2bH6Pd")

• The user's ID ("user": "23945872938472")

• The user's connected wallet and email (if applicable)

• The campaign ID and name ("campaign": { "id": "sue7r1vO", "name": "Test campaign" })

• Details about the specific event, such as the task ID, type, and name ("event": { "type": "action_completed", "data": { "action": { "id": "_g06CbGQ", "name": "reCAPTCHA", "type": "recaptcha" } } })

How to use this data

You can utilize this real-time data to:

• Update user progress and rewards within your own applications.

• Trigger personalized notifications or messages based on user actions.

• Track campaign performance and identify areas for improvement.

• Integrate with other tools and services (e.g., send data to analytics platforms or trigger actions in Zapier).

Test your webhook

claimr allows you to test your webhook setup to ensure it's working correctly.

Testing your webhook

1. Acess the test environment: In the API section of your claimr admin panel, you'll find a dedicated area for testing webhooks.

2. Input a test User ID: Enter a test User ID in the provided field.

3. Initiate the test: Click Test button to send a simulated user activity event to your webhook endpoint.

4. Verify the Response: claimr will display a response indicating whether the test message was successfully sent. You should also check your endpoint to confirm that it received the data.

Test example

This example shows the detailed information included in a webhook payload, such as user data, campaign details, event type, and associated points and rewards.

{
  "id": "lisjywHXKAq6yQe2bH6Pd",
  "scope": "user_activity",
  "user": "23945872938472",
  "wallet": "",
  "email": "",
  "campaign": {
    "id": "sue7r1vO",
    "name": "Test campaign"
  },
  "event": {
    "type": "action_completed",
    "data": {
      "action": {
        "id": "_g06CbGQ",
        "name": "Test action",
        "type": "test_action"
      },
      "xp": 100
    }
  },
  "total_xp": 1500,
  "ref_xp": 50,
  "ugc_xp": 25,
  "xp_mul": 1.1,
  "rank": 1,
  "team": "red pill"
}

Explanation of the fields

id: A unique identifier for this specific webhook message.

scope: Indicates the type of event that triggered the webhook (e.g., user_activity).

user: The ID of the user who performed the action that triggered the webhook.

wallet: The user's connected wallet address, if applicable.

email: The user's email address, if available.

campaign: Contains information about the campaign where the action occurred, including:

id: The unique ID of the campaign.

name: The name of the campaign.

event: Details about the specific event that triggered the webhook, including:

type: The type of event (e.g., action_completed, quest_completed).

data: Additional data related to the event, such as:

action: Information about the completed action, including its ID, name, and type.

xp: The number of experience points awarded for completing the action.

total_xp: The user's total accumulated experience points.

ref_xp: The amount of XP the user has earned from referrals.

ugc_xp: The amount of XP the user has earned from user-generated content.

xp_mul: The multiplier applied to the XP earned for this action.

rank: The user's current rank in the campaign leaderboard.

team: The user's team, if applicable.

Configuring multiple endpoints

In claimr, you can configure multiple endpoints for a single webhook. Each endpoint will receive the same webhook payload whenever the associated event is triggered. When registering a webhook in Swagger (or through other methods), you can provide a list of endpoint URLs instead of just one.

Why use multiple endpoints?

• Mirroring data to multiple servers for redundancy.

• Sending different types of data to different applications or services.

• Integrating with multiple analytics or monitoring tools.

If you're using multiple endpoints for the same scope, it's recommended to assign a unique hook_id to each webhook for easier management and tracking.

Retry policy

In situations where your server may experience temporary downtime or unresponsiveness, claimr employs a retry policy to ensure the reliable delivery of webhook notifications.

Understanding retry policy

A retry policy is a mechanism that attempts to redeliver webhook messages if the initial delivery attempt fails due to server unavailability. claimr's retry policy utilizes increasing intervals between attempts, allowing time for your server to recover and become responsive.

claimr's retry intervals

• First retry: 5 seconds after the initial attempt.

• Second retry: 30 seconds after the first retry.

• Third retry: 1 minute after the second retry.

• Final retry: 5 minutes after the third retry.

Undelivered events

If all retry attempts prove unsuccessful, the event will be recorded as undelivered. This allows you to investigate potential issues and take necessary action to ensure future notifications are delivered successfully.