> For the complete documentation index, see [llms.txt](https://docs.claimr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claimr.io/webhooks/assign-webhooks.md).
# Assign webhooks
claimr provides pre-defined webhooks that you can assign to send real-time data to your applications when specific events occur. This allows you to integrate claimr with other systems and automate workflows.
## Webhook types
* **User activity hook:** Triggered when a user acts within a campaign (e.g., completes a task, claims a reward).
* **User login hook:** Triggered when a user logs in to claimr.
* **User reward hook:** Triggered when a user claims a reward.
* **Referral hook:** Triggered when a referral-related event occurs (e.g., a new user signs up via a referral link).
## **Assign a webhook**
1. **Navigate to the API Section:** In your claimr dashboard, go to the "API" section.
2. **Locate the webhook:** Find the webhook you want to assign (e.g., "User activity hook").
3. **Click "Assign":** Click **Assign** button next to the webhook. This will open an **Assign webhook** modal window.
4. **Fill in the Webhook Configuration:** Within the modal window, you'll configure the webhook settings:
* **ID:** A unique identifier for your webhook. It is automatically generated by claimr but can be edited.
* **URL:** This is the URL of the external endpoint that will receive the webhook data. This must be a publicly accessible endpoint that can accept HTTP POST requests. You'll need to obtain this URL from the application you're integrating with.
* **Secret:** A secret key used to verify the authenticity of the webhook requests. When you set a secret, claimr will use it to generate a signature that's included with each webhook request. Your receiving application should verify this signature to ensure the request came from claimr and hasn't been tampered with.
* **Campaigns:** This section allows you to specify which campaigns this webhook applies to.
* If you leave this section empty (no checkboxes selected), the webhook will be triggered for *all* your campaigns.
* If you select one or more campaigns, the webhook will *only* be triggered for events within those specific campaigns.
5. **Click "Assign":** Once you've filled in the configuration, click **Assign** to save the settings.
## 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.
## Testing your webhook
claimr provides a built-in testing tool to verify that your webhook integration is working correctly before you go live. This allows you to simulate a webhook event and see the data that would be sent to your endpoint.
1. **Access the test environment:** Navigate to the "API" section of your claimr admin panel, find the webhook you want to test (e.g., "User activity hook"). You should see a testing area associated with that webhook.
2. **Input a test User ID:** Enter a valid claimr User ID into the "User:" field.
3. **Initiate the test:** Click the "Test" button. This will trigger a simulated `user_activity` event for the specified user.
4. **Verify the response:**
* **Response Body:** claimr will display the *exact* JSON payload that would be sent to your webhook endpoint in the "Response body:" section. Carefully review this data to ensure it matches the expected format and contains all the necessary information.
* **Response Result:** claimr will also show a summary of the test result:
* **Success:** A boolean value (`true` or `false`) indicating whether claimr was able to send the test message. Note that this only confirms that claimr sent the message; it does not guarantee that your endpoint received it successfully.
* **Status:** The HTTP status code returned by your endpoint (if it was reached). A status code of `200` indicates success on your endpoint's side.
* **Data:** This will usually display a snippet of the response from *your* server. If your server is set up to return a confirmation message, you'll see it here. If your server returned an error, or if the request failed to reach your server, you might see an error message or HTML code here.
### **Test example**
Check an example of a successful test. The "Response body:" section displays the JSON payload that was sent.
\
Here's a breakdown of the fields in the example payload:
* **`id`:** A unique identifier for this specific webhook message.
* **`scope`:** Indicates the webhook was triggered by a user activity event.
* **`user`:** The ID of the user who performed the action.
* **`user_id`:** The ID of the user.
* **`wallet`:** The user's connected wallet address.
* **`email`:** The user's email address.
* **`campaign`:** Information about the campaign.
* **`id`:** The unique ID of the campaign.
* **`name`:** The name of the campaign.
* **`event`:** Details about the specific event.
* **`type`:** The type of event (an action was completed).
* **`data`:** Additional data about the event.
* **`account`:** The associated account.
* **`action`:** Information about the completed action.
* **`id`:** The action's ID.
* **`name`:** The action's name.
* **`type`:** The action's type.
* **`meta`:** The additional metadata.
* **`xp`:** The number of points awarded.
* **`total_xp`:** The user's total points.
* **`ref_xp`:** Points earned from referrals.
* **`ugc_xp`:** Points earned from user-generated content.
* **`xp_mul`:** The points multiplier.
* **`rank`:** The user's rank.
* **`team`:** The user's team.
The "Response result:" section shows `Success: true` and `Status: 200`, indicating that the test message was sent successfully and your endpoint (presumably) responded with a success code.
{% hint style="info" %}
The testing tool simulates the webhook event from the claimr's side. It's still important to ensure your endpoint is correctly configured to receive and process the webhook data.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.claimr.io/webhooks/assign-webhooks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.