# Webhooks Overview

The Firstup Webhooks API lets you subscribe to events within the platform so your systems can automatically react when something happens — for example, when content is published, a user is updated, or engagement data changes.

Webhook deliveries are sent as HTTP POST requests containing JSON payloads to your configured endpoint. Each event has a specific schema, version, and metadata describing the source subscription and delivery.

## Register a Webhook

Webhook subscriptions are managed through the [/v2/webhooks/subscriptions](/endpoints/openapi/webhooks/createwebhooksubscription) endpoint.

**Example Request**


```
POST https://partner.<region>.onfirstup.com/v2/webhooks/subscriptions
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "url": "https://example.com/webhook",
  "authorization_header": "Bearer my-secret",
  "active": true,
  "events": [
    { "name": "content_published", "version": "1" }
  ]
}
```

### Required Scopes

* `webhooks.write` — to create or update subscriptions
* `webhooks.read` — to view existing subscriptions


### Webhook Subscription Attributes

| Firstup Attribute | Description |
|  --- | --- |
| `url` | HTTPS endpoint that receives POST deliveries. |
| `authorization_header` | (Optional) Custom header sent with every delivery, typically a bearer token used by your server for authentication. |
| `active` | Boolean flag to enable or disable the subscription. Only active subscriptions send deliveries. |
| `events` | Array of event objects. Each object defines the name (e.g., content_published) and version (currently "1"). |


### Webhook Request With Headers

When an event is delivered to your endpoint, Firstup includes these headers:

| Header | Description |
|  --- | --- |
| `content-type` | Always application/json. |
| `authorization` | Set to the value configured in your subscription’s authorization_header (if provided). |
| `x-socialchorus-delivery` | Unique ID for this webhook delivery, matching delivery.id in the payload. Use this for logging and idempotency. |


**Example Delivery Request**


```
POST /webhook HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer my-secret
X-SocialChorus-Delivery: abc123-456
```

## Content Published Event

This is a webhook payload example — Content Published Event.

Each webhook delivery wraps event data in a delivery envelope. The outer structure matches the `Webhooks.Delivery.Resource` schema; the inner data depends on the event type.

**Example Payload**


```
{
  "delivery": {
    "id": "abc123-456",
    "status": "success"
  },
  "subscription": {
    "id": "sub_789",
    "url": "https://example.com/webhook"
  },
  "event": {
    "name": "content_published",
    "version": "1",
    "timestamp": "2025-11-14T10:30:00Z",
    "data": {
      "content_id": 456,
      "title": "Example Post Title",
      "state": "published",
      "published_at": "2025-11-14T10:29:58Z",
      "permalink_url": "https://onfirstup.com/acme/acmetimes/sc4#contents/456"
    }
  }
}
```

The `event.data` section varies by event type. For example, `content_published` includes post metadata, whereas `user.updated` includes user identifiers.

## Test a Webook

To verify a webhook subscription, use the [ping endpoint](/endpoints/openapi/webhooks/pingwebhooksubscription). This sends a sample payload to your configured URL.

`POST /v2/webhooks/subscriptions/{subscription_id}/ping`

**Example Request**


```
curl -X POST https://partner.<region>.onfirstup.com/v2/webhooks/subscriptions/abc123/ping \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

**Example Response**


```
{
  "data": {
    "delivery": {
      "id": "abc123-456",
      "status": "success"
    },
    "subscription": {
      "id": "abc123",
      "url": "https://example.com/webhook"
    }
  }
}
```

A 200 response means your webhook endpoint was reachable and accepted the ping. If your endpoint returns a 5xx status, Firstup retries the delivery up to 5 times.

## Webhook Pagination

Listing webhook subscriptions supports cursor-based pagination.

**Example Request**

`GET /v2/webhooks/subscriptions?page.size=10`

**Example Response**


```
{
  "data": [ ... ],
  "meta": {
    "pagination": {
      "cursor": "current-cursor-value",
      "next": "next-cursor-value",
      "page_size": 10
    }
  }
}
```

To fetch the next page, pass the `meta.pagination.next` value as the cursor in your next request:

`GET /v2/webhooks/subscriptions?page.cursor=next-cursor-value`

Refer to [Pagination Overview](https://developers.firstup.io/gettingstarted/pagination) for more guidance on pagination.

## Delete or Update A Subscription

**Update**


```
PUT /v2/webhooks/subscriptions/{subscription_id}
{
  "active": false,
  "events": [{ "name": "content_archived", "version": "1" }]
}
```

**Delete**

`DELETE /v2/webhooks/subscriptions/{subscription_id}`

Deleting permanently removes the subscription and stops all deliveries.

## Common Errors

| HTTP code | Meaning | Typical cause |
|  --- | --- | --- |
| 400 | Bad request | Invalid body structure, missing required field (e.g., missing events array). |
| 401 | Unauthenticated | Token invalid or missing. |
| 403 | Unauthorized | Token lacks the required `webhooks.write` scope. |
| 404 | Not found | Subscription ID does not exist in this program |


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

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.