Skip to content
/
Webhooks Overview
Last updated

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 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 AttributeDescription
urlHTTPS endpoint that receives POST deliveries.
authorization_header(Optional) Custom header sent with every delivery, typically a bearer token used by your server for authentication.
activeBoolean flag to enable or disable the subscription. Only active subscriptions send deliveries.
eventsArray 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:

HeaderDescription
content-typeAlways application/json.
authorizationSet to the value configured in your subscription’s authorization_header (if provided).
x-socialchorus-deliveryUnique 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. 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 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 codeMeaningTypical cause
400Bad requestInvalid body structure, missing required field (e.g., missing events array).
401UnauthenticatedToken invalid or missing.
403UnauthorizedToken lacks the required webhooks.write scope.
404Not foundSubscription 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.

Previous page
Next page