# Engagement Tracking via Webhooks

Understanding how employees interact with content is essential for measuring engagement and optimizing communication strategies. With Firstup’s Webhook API, you can track engagement activities—such as likes, comments, and shares—by automatically sending this data to external analytics tools, dashboards, or CRM systems.

## Prerequisites

Before setting up engagement tracking, ensure that:

1. You have a publicly accessible endpoint that can receive webhook events (e.g., an analytics platform or a business intelligence tool).
2. You have API access to register webhooks via the `POST /v2/webhooks/subscriptions` endpoint.
3. You have permissions to fetch engagement data using the `GET /v2/feed/posts/{content_id}` API if you need additional engagement details.


## Step 1: Creating the Webhook Subscription

To receive notifications when users engage with content, register a webhook that listens for `engagement.liked`, `engagement.commented`, and `engagement.shared` events.

**Example Request to Create a Webhook**


```
POST /v2/webhooks/subscriptions
{
  "name": "Engagement Tracking Webhook",
  "url": "https://your-analytics-platform.com/api/firstup-webhook",
  "events": ["engagement.liked", "engagement.commented", "engagement.shared"],
  "active": true
}
```

| Firstup Attribute | Description |
|  --- | --- |
| `name` | A descriptive name for your webhook. |
| `url` | The external system’s endpoint that will receive webhook notifications. |
| `events` | The event type(s) to listen for. In this case, engagements (likes, comments, shares). |
| `active` | Specifies whether the webhook is active. |


## Step 2: Handling the Webhook Event

Once registered, your external system will receive a `POST` request from Firstup whenever an engagement action (like, comment, or share) occurs.

**Example Webhook Payload (Like Event)**


```
{
  "event": "engagement.liked",
  "timestamp": "2025-03-26T14:20:00Z",
  "data": {
    "userId": "56789",
    "userName": "alice.smith",
    "contentId": "12345",
    "feedId": "98765",
    "engagementType": "like",
    "createdAt": "2025-03-26T14:19:59Z"
  }
}
```

Your analytics platform should parse this data and log the engagement.

**Example Webhook Payload (Comment Event)**


```
{
  "event": "engagement.commented",
  "timestamp": "2025-03-26T14:22:00Z",
  "data": {
    "userId": "56789",
    "userName": "alice.smith",
    "contentId": "12345",
    "feedId": "98765",
    "engagementType": "comment",
    "commentText": "Great article!",
    "createdAt": "2025-03-26T14:21:59Z"
  }
}
```

This payload contains the comment text, which can be stored or analyzed for sentiment.

**Example Webhook Payload (Share Event)**


```
{
  "event": "engagement.shared",
  "timestamp": "2025-03-26T14:25:00Z",
  "data": {
    "userId": "56789",
    "userName": "alice.smith",
    "contentId": "12345",
    "feedId": "98765",
    "engagementType": "share",
    "sharedTo": "LinkedIn",
    "createdAt": "2025-03-26T14:24:59Z"
  }
}
```

Here, the webhook indicates that a user has shared content externally (e.g., to LinkedIn).

## Step 3: Getting Additional Engagement Details (Optional)

If your system needs more information about a specific piece of content’s engagement history, you can retrieve it using the `GET /v2/feed/posts/{content_id}` endpoint.

**Endpoint**

GET /v2/feed/posts/{content_id}
**Example Request to Fetch Engagement Data**


```
GET /v2/feed/posts/98765
Authorization: Bearer YOUR_ACCESS_TOKEN
```

**Example Response**


```
{
  "feedId": "98765",
  "contentId": "12345",
  "engagements": [
    {
      "userId": "56789",
      "userName": "alice.smith",
      "engagementType": "like",
      "createdAt": "2025-03-26T14:19:59Z"
    },
    {
      "userId": "56789",
      "userName": "alice.smith",
      "engagementType": "comment",
      "commentText": "Great article!",
      "createdAt": "2025-03-26T14:21:59Z"
    }
  ]
}
```

This provides a history of engagement actions on a particular post.