# 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**

POST /v2/webhooks/subscriptions
**Example Request: Register a Webhook**


```json
POST /v2/webhooks/subscriptions
{
  "name": "Content Published Webhook",
  "url": "https://yourserver.com/webhook-endpoint",
  "events": ["content.published"],
  "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. |
| `active` | A boolean value that specifies whether the webhook is active. |


**Example Webhook Payload: Content Published Event**


```json
{
  "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](/webhooks/webhook-events#creating-a-subscription) 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

GET /v2/webhooks/subsciptions
Get a list of all registered webhooks.

GET /v2/webhooks/subscriptions/{subscriptionId}
View details of a specific webhook.

PUT /v2/webhooks/subscriptions/{subscriptionId}
Update webhook configurations (e.g., change the target URL).

DELETE /v2/webhooks/subscriptions/{subscriptionId}
Remove a webhook subscription when it is no longer needed.

## Example Use Cases

Automated Content Sharing
Set up a webhook to notify your external CMS or intranet whenever new content is published in Firstup.

User Management Syncing
Automatically update your internal HR system when a user’s profile is modified.

Engagement Tracking
Capture likes, comments, or shares in your external analytics platform for deeper insights.

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.