Webhooks Overview

Webhooks are a powerful way to receive real-time updates from the Firstup platform without the need for continuous polling. They allow external systems to be notified whenever specific events occur in your Firstup environment, such as new content being published, user profile updates, or engagement actions like likes and comments.

With Firstup’s Webhook API, you can configure webhook subscriptions to automatically send event data to your specified URL whenever a triggering event occurs. This enables seamless integration with external applications, analytics tools, or internal systems that need to react to platform activity in real time.

Why Use Firstup Webhooks?

With Firstup Webhooks, you can:

• Automate content workflows by sharing published posts to external platforms.
• Synchronize user management across multiple systems by capturing profile updates.
• Track engagement metrics in real-time to analyze likes, comments, and shares.
• Integrate with external tools like CRMs, analytics dashboards, or messaging platforms.

By leveraging webhooks, organizations can ensure their communication and engagement strategies are always up to date and responsive.

How Firstup Webhooks Work

Firstup webhooks operate through an event-driven model. When a relevant event occurs (e.g., content is published, a user profile is updated, or engagement actions happen), Firstup sends a POST request containing event details to the designated webhook URL.

Webhook Event Flow

1. Create a Webhook Subscription: Register a webhook with Firstup, specifying which events to listen for and providing a target endpoint URL.
2. Receive Event Notifications: When the specified event occurs, Firstup sends a structured JSON payload to your endpoint.
3. Process and Respond: Your system processes the webhook data and executes relevant actions, such as updating records, triggering alerts, or syncing data.
4. Manage Webhooks: Modify, deactivate, or delete webhooks as needed to maintain control over event processing.

Setting Up a Webhook (Quick start)

To create a webhook in Firstup, provide the following details:

Endpoint

Example Request: Register a Webhook

POST /v2/webhooks/subscriptions
{
  "name": "Content Published Webhook",
  "url": "https://yourserver.com/webhook-endpoint",
  "events": ["content.published"],
  "active": true
}

Example Webhook Payload: Content Published Event

{
  "event": "content.published",
  "timestamp": "2025-03-26T14:20:00Z",
  "data": {
    "contentId": "12345",
    "title": "New Company Announcement",
    "publishedAt": "2025-03-26T14:19:59Z",
    "author": "jane.doe",
    "channelId": "67890"
  }
}

Your system should parse this payload and handle it accordingly—such as forwarding the content to an external platform or storing it in an internal database.

Click here for a detailed look at creating a subscription.

Authentication

All webhook events sent by Firstup include an optional Authorization header if specified during webhook registration.

Use this header to verify the authenticity of incoming requests.

Delivery and Retry Behavior

Webhooks are delivered via HTTPS POST requests.

A successful delivery is determined by an HTTP status code in the 2xx range.

Failed deliveries (non-2xx responses) will be retried:

• Up to 5 times
• With exponential backoff delays

To ensure delivery, your endpoint must respond within 5 seconds.

Validating Webhook Requests

If your webhook subscription includes an Authorization header (e.g., Bearer YOUR_SECRET), validate incoming requests by comparing the Authorization value against your expected token. This ensures that only authorized calls from Firstup are accepted.

Optionally, you may use HMAC signatures or request signing for more advanced validation.

Example Webhook Request with Headers

POST /webhook-endpoint HTTP/1.1
Host: yourserver.com
Content-Type: application/json
Authorization: Bearer secret-token
User-Agent: Firstup-Webhook/1.0

{
  "event": "content_published",
  "content_id": "abc123",
  "channel_id": "newsroom"
}

Testing Webhooks

To verify integration, Firstup allows sending ping events to confirm connectivity and signature validation.

Example:

{
  "event": "ping",
  "timestamp": "2025-06-27T18:00:00Z"
}

Security Considerations

To ensure webhook security:

• Use HTTPS endpoints to protect data transmission.
• Implement signature validation to verify webhook authenticity.
• Use rate limiting to prevent overloading your system with webhook requests.

Pagination for Webhook Subscriptions

Webhook subscription listings use cursor-based pagination, which is ideal for retrieving large or dynamic result sets efficiently and reliably.

When you request a list of webhook subscriptions:

GET /v2/webhooks/subscriptions

The response includes a meta.pagination object that contains the current cursor and the next value (used to fetch the next page):

{
  "data": [ ... ],
  "meta": {
    "pagination": {
      "cursor": "cursor123",
      "next": "cursor456",
      "page_size": 25
    }
  }
}

To retrieve the next page, pass the cursor value from meta.pagination.next in your next request:

GET /v2/webhooks/subscriptions?cursor=cursor456

You can also specify a custom page size:

GET /v2/webhooks/subscriptions?cursor=cursor456&page.size=50

Always use the next cursor returned by the previous response. Avoid hardcoding or reusing old cursor values, as results may change over time.

Example Flow

Initial request:

GET /v2/webhooks/subscriptions?page.size=25

Response includes:

{
  "meta": {
    "pagination": {
      "cursor": "abc123",
      "next": "def456",
      "page_size": 25
    }
  }
}

Request next page:

GET /v2/webhooks/subscriptions?cursor=def456&page.size=25

Repeat this. Continue using the next value from each response until it is omitted or null.

Managing Webhooks

Example Use Cases

By leveraging Firstup’s webhooks, you can create a more dynamic and responsive ecosystem that extends the reach and impact of your employee communication strategy.