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:

You have a publicly accessible endpoint that can receive webhook events (e.g., an analytics platform or a business intelligence tool).
You have API access to register webhooks via the POST /v2/webhooks/subscriptions endpoint.
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.