# Automated Content Sharing

Automated Content Sharing webhooks let your integration automatically respond when content is published or archived in a Firstup program.

Typical use cases include:

* Syndicating new posts to external channels such as Slack, SharePoint, or another Firstup program.
* Triggering workflows in your CMS or marketing automation tools when a new post goes live.
* Removing or updating mirrored content when posts are archived.


Webhooks notify your system in real time so you can decide what to do next.

## Event Triggers

| Event Name | When it Fires | Example Use Case |
|  --- | --- | --- |
| `content_published` | Whenever a post changes state to “published.” | Push new posts to an external system, auto-share on Slack, or start a content replication workflow. |
| `content_archived` | When a post is archived or removed. | Deactivate or unpublish mirrored posts in other platforms. |


## Registering the Webhook

Create a webhook subscription to receive `content_published` or `content_archived` events.

**Example Request**


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

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

## Required Scopes

* `webhooks.write` — to create or update subscriptions
* `content.read` — if your service will later fetch post details via the Content Publishing API


## Webhook Subscription Attributes

| Firstup Attribute | Description |
|  --- | --- |
| `url` | The external system’s endpoint that will receive webhook notifications. |
| `authorization_header` | (Optional) Static header sent in each request, often used to authenticate inbound calls on your server. |
| `events` | Array of { name, version } objects defining the events you want to receive. Example: { "name": "content_published", "version": "1" }. |
| `active` | Boolean that enables or disables the subscription. Inactive subscriptions only respond to /ping. |


## Example Webhook Delivery

Webhook deliveries follow the schema defined in `Webhooks.Delivery.Resource`. Each payload contains delivery metadata, the subscription reference, and the event object.


```
{
  "delivery": {
    "id": "abc123-456",
    "status": "success"
  },
  "subscription": {
    "id": "sub_789",
    "url": "https://example.com/webhooks/firstup"
  },
  "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"
    }
  }
}
```

## Delivery Headers

| Header | Description |
|  --- | --- |
| `Content-Type` | Always application/json. |
| `Authorization` | Set to the value of your subscription’s authorization_header (if provided). |
| `X-SocialChorus-Delivery` | Unique identifier of the webhook delivery, matching delivery.id in the payload. |


Use X-SocialChorus-Delivery for idempotency and traceability when logging or retrying events.

## Recommended Automation Flow

1. Receive content_published event via webhook.
2. Validate the delivery signature or Authorization token.
3. Fetch content details using:



```
GET /v2/content/{content_id}
Authorization: Bearer <APP_TOKEN>
```

Example use: build a JSON or formatted message for Slack, SharePoint, or Teams.

1. Publish externally — your system decides where and how to distribute it.
2. Track replication (optional) via:


`GET /v2/content/replications?filter.source.contentId={content_id}`

This endpoint provides replication audit data (source, target platform, timestamps).

Webhooks do not create replications automatically, they simply trigger your automation.

## Test your Webhook

You can test your subscription without waiting for a live event using the [ping endpoint](/endpoints/openapi/webhooks/pingwebhooksubscription).

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

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

## Best Practices

* Use a unique authorization_header token per integration partner.
* Verify the token in your handler before processing payloads.
* Return a 2xx response quickly; longer processing should happen asynchronously.
* Log the X-SocialChorus-Delivery header to correlate retries.
* Webhooks retry automatically on any 5xx response.