Organization Social Action Notifications
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
The Organization Social Actions Notifications API enables your app to notify members about activity on their LinkedIn Company Pages. Use this API to build real-time streams for activity on LinkedIn Company Pages.
Note
All API request examples in this document are represented in protocol 2.0.0. Use the header X-Restli-Protocol-Version: 2.0.0 to follow these examples. All URNs must be URL encoded in order to use Restli Protocol 2.0.0. For example, a colon should be translated to "%3A", so urn:li:organization:12345 is encoded to urn%3Ali%3Aorganization%3A12345.
Permissions
| Permission | Description |
|---|---|
| rw_organization_admin | Manage organizations pages and retrieve reporting data. Restricted to organizations in which the authenticated member has the following role:
|
Webhook Registration and Validation
To receive notifications at your webhook, your webhook must be registered and validated. Please review and complete the steps in the documentation for Webhooks.
Event Subscription API
In order to receive notifications on your validated webhook, you must also subscribe your members using the Subscription API.
Security
Subscriptions must be authorized with the rw_organization_admin permission by each member who is receiving notifications. See Organization Access Control for information on how to retrieve roles through the API. Additionally, the ability to subscribe to and access an organization’s data through the Organization Social Actions Notifications API is governed by the authenticated member’s administrative access to the organization. Review and understand the implications of access control and member authorization on the lifetime of subscriptions.
Subscription Lifetime
Your app’s subscriptions for a member are only valid for as long as the member's authorization grant is valid for your application. If the grant expires or if the member revokes their grant for your application, the subscriptions for the member will be removed. A subscription will also be removed in the case that the member is no longer an administrator of the company they are subscribed to.
You must properly handle these subscription change events in order to resume getting notifications. Failure to correctly handle the various subscription changes will lead to some notifications not being delivered to members. Managing Subscription Changes section covers the steps you should follow.
Creating and Updating Subscriptions
A subscription record contains details of the subscription including the webhook URL where your app will receive notifications. Each subscription record is uniquely identified by your app, the member, the organizational entity and the eventType. You must specify your developerApplication, member, entity, and eventType as the key in your upsert calls to either create a subscription or update a subscription with a new webhook URL.
Ensure that the webhook URL is registered and validated. The webhook must be able to process the notification payload sent by LinkedIn and return a 2xx response upon success. Review the Webhook documentation for more details.
The subscription request will only succeed if the subscribing member is an administrator of the organization being subscribed to.
Event Subscription Sample Request
PUT https://api.linkedin.com/rest/eventSubscriptions/(developerApplication:urn:li:developerApplication:{developer application ID},user:urn:li:user:{member ID},entity:urn:li:organization:{organization ID},eventType:ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS)
{
"webhook": "https://www.example.com/callback"
}
PUT https://api.linkedin.com/v2/eventSubscriptions/(developerApplication:urn:li:developerApplication:{developer application ID},user:urn:li:user:{member ID},entity:urn:li:organization:{organization ID},eventType:ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS)
{
"webhook": "https://www.example.com/callback"
}
Resource Key Fields
| Field | Type | Description | Required |
|---|---|---|---|
| developerApplication | URN | The URN of your developer application. Must be in the format urn:li:developerApplication:{id}. Your developer application id can be found within the URL of your application in the developer application portal | Yes |
| user | URN | The Person URN of the authenticated user. Must be in the format urn:li:person:{id}. | Yes |
| entity | URN | The organizational entity being subscribed to. Must be in the format urn:li:organization:{id}. | Yes |
| eventType | String | Notification type being subscribed to. Supported values:
|
Yes |
Retrieve Subscriptions by Key
Sample Request
Sample Response
{
"entity": "urn:li:organization:12345",
"eventType": "ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS",
"user": "urn:li:person:abCdef",
"expiresAt": "1536130694583",
"webhook": "https://www.example.com/callback"
}
Retrieve Subscriptions for an Authenticated Member
Sample Request
Sample Response
{
"elements": [
{
"entity": "urn:li:organization:12345",
"eventType": "ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS",
"user": "urn:li:person:abCdef",
"expiresAt": "1536130694583",
"webhook": "https://www.example.com/callback"
},
{
"entity": "urn:li:organization:45678",
"eventType": "ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS",
"member": "urn:li:person:abCdef",
"expiresAt": "1537176459876",
"webhook": "https://www.example.com/callback"
},
{
"entity": "urn:li:organization:45678",
"eventType": "ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS",
"member": "urn:li:person:ghijkl",
"expiresAt": "1537176459876",
"webhook": "https://www.example.com/callback"
}
],
"paging": {
"count": 10,
"links": [
"href": "/eventSubscriptions?count=10&start=10&q=subscriber",
"rel": "next",
"type": "application/json"
],
"start": 0
}
}
Remove a Subscription
Sample Request
Returns 200 OK on success
Managing Subscription Changes
A subscription's validity is tied to the member’s access to the subscribed organization and their authorization for your app. You must ensure the following steps are taken to handle subscriptions that have been removed:
- Track the timestamp of when the last notification was successfully received for each member.
- Check if the authenticated member is no longer subscribed. You can identify dropped subscriptions by doing both of:
- Handling 401 and 403 errors returned by calls to LinkedIn Organization APIs.
- A 401 error indicates that your application is no longer authorized by the member. You must acquire a new grant from the member before resubscribing.
- A 403 error indicates that the member is no longer an administrator of the company. This member should no longer be receiving notifications for that company, and will no longer be able to resubscribe to that company.
- On a suitable cadence, query the organizations that the member currently administers and their active subscriptions to identify which of their current companies they are no longer subscribed to.
- Handling 401 and 403 errors returned by calls to LinkedIn Organization APIs.
- Notifications for the member and organization will not be sent to your webhook during the period of time when the member did not have an active subscription. Use the timestamp the member last received notifications to query missed notifications.
- Resubscribe the member with a valid access token to resume getting notifications for the member. You can use the notificationId in the notification payload to dedupe events you already pulled in Step 3.
Receive Webhook Push Notifications
Registered webhook URLs will receive notifications from LinkedIn for subscribed events.
Note
Before sending a notification, LinkedIn will validate that the subscribed member has continued administrative access to the organization and has a valid authorization. The notification will be skipped if these access requirements are not met at the time of the event.
OrganizationSocialActionNotificationEventsPayload Schema
| Field | Type | Description |
|---|---|---|
| type | string | Type of the push event. Possible values:
|
| notifications | optional OrganizationSocialActionNotification[] | List of notifications |
OrganizationSocialActionNotification Schema
| Field | Type | Description |
|---|---|---|
| notificationId | long | Global unique identifier to ensure notification uniqueness. |
| organizationalEntity | Urn | The Organization Urn for which the notification belongs. |
| action | string | Action type that triggered the notification. Possible values:
|
| sourcePost | Urn | The activity or article Urn that the member acted on, e.g. the activity that member liked, the article that member shared. |
| decoratedSourcePost | Share | The decorated share the member acted on. This field may not be populated if there was an error when decorating the share. |
| lastModifiedAt | long | Timestamp of the last modification of the notification. |
| generatedActivity | Urn | An activity or comment Urn as a result of acting on the target, e.g. a comment entity generated when a member commented on an activity, article, etc. It exists for COMMENT, ADMIN_COMMENT, COMMENT_EDIT, COMMENT_DELETE, and SHARE_MENTION. |
| decoratedGeneratedActivity | [Share, Comment] | The decorated generated activity created as a result of acting on the sourcePost. E.g. a comment on an article or a share. This field may not be populated if there was an error when decorating the generated activity. |
| subscriber | Urn | member that created the subscription. If there is more than 1 subscription for a given organization each subscriber will get an event with the same notificationId but different subscriber. |
Share Schema
| Field | Type | Description |
|---|---|---|
| entity | Urn | The unique urn of the share |
| owner | Urn | Urn of the entity which owns the share. |
| text | string | Text entered by the member for this share. |
| title | string | member supplied title of the content. |
| description | string | member supplied description of the content. |
| landingPageUrl | Url | The main landing page URL of the share. |
| mediaCategory | string | The category of media shared:
|
Comment Schema
| Field | Type | Description |
|---|---|---|
| entity | Urn | The unique urn of the comment |
| owner | Urn | The owner of the comment. Allowed urn types for now are OrganizationUrn, OrganizationBrandUrn, and PersonUrn. |
| object | Urn | The object to which this action should be attributed. E.g. for comments on a share, the object of both the nested and top level comments is the share urn. |
Notification Payload
Notifications sent to each webhook are batched by the event type (ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS) with a batch size of 10. Notifications contain only URNs of entities related to the notification.
Sample Payload
{
"type": "ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS",
"notifications": [
{
"generatedActivity": "urn:li:share:6343443434841538048",
"decoratedGeneratedActivity": {
"share": {
"entity": "urn:li:share:6343443434841538048",
"owner": "urn:li:organization:523424",
"text": "This is a some share text",
"landingPageUrl": "www.linkedin.com",
"mediaCategory": "IMAGE"
}
},
"lastModifiedAt": 1535741251282,
"notificationId": 4406004,
"sourcePost": "urn:li:activity:29292929292992929292",
"decoratedSourcePost" : {
"entity": "urn:li:share:343443",
"owner": "urn:li:person:5234",
"text": "This is a some share text",
"landingPageUrl": "www.linkedin.com",
"mediaCategory": "ARTICLE"
},
"action": "SHARE",
"organizationalEntity": "urn:li:organization:12345",
"subscriber": "urn:li:person:abcdedf"
},
{
"generatedActivity": "urn:li:comment:(activity:63434434348, 12345)",
"decoratedGeneratedActivity": {
"comment": {
"entity": "urn:li:comment:(urn:li:activity:63434434348, 12345)",
"owner": "urn:li:person:523424",
"object": "urn:li:activity:56459853495",
"text": "This is a some share text"
}
},
"lastModifiedAt": 1535741251282,
"notificationId": 4406004,
"sourcePost": "urn:li:activity:29292929292992929293",
"decoratedSourcePost" : {
"entity": "urn:li:share:343443",
"owner": "urn:li:person:5234",
"text": "This is a some share text",
"landingPageUrl": "www.linkedin.com",
"mediaCategory": "ARTICLE"
},
"action": "COMMENT",
"organizationalEntity": "urn:li:organization:12345",
"subscriber": "urn:li:person:abcdedf"
},
{
"generatedActivity": "urn:li:share:7343443434841538048",
"lastModifiedAt": 1535741251282,
"notificationId": 4406004,
"sourcePost": "urn:li:activity:49292929292992929292",
"action": "SHARE",
"organizationalEntity": "urn:li:organization:67890",
"subscriber": "urn:li:person:abcdedf"
}
]
}
Review the OrganizationSocialActionNotification Schema to understand the data returned, and the mapping below to identify the APIs that can be used to retrieve the details of each entity using the Urns returned in the notification.
Urn Types and Retrieval APIs
| Field | Type of Urn | Retrieval APIs | Retrieval API Purpose |
|---|---|---|---|
| organizationalEntity | Organization Urn | Organizations API | Retrieve information about the company page that the notification is related |
| sourcePost | Activity Urn Article Urn | Activity API Article API | Retrieve information about the parent share on which the event occurred. |
| generatedActivity | Share Urn Comment Urn | Shares API Social Actions API | Retrieve information about the entity related to the event that triggered the notification (share or comment). |
| subscriber | Person Urn | Basic Profile API | Use the personUrn to identify the member who the notification should be delivered to. The personUrn is typically sufficient for this and you may not need to make a call to the Basic Profile API. |
Message Reliability
LinkedIn will attempt to redeliver the notification once every 5 minutes for 8 hours, after which redelivery attempts for that notification will be aborted. In case of webhook downtimes over 8 hours, you can query the missed notifications.
Error Handling
The notification payload contains a notificationId and lastModifiedAt timestamp. You should use these values to deduplicate notifications and keep track of the notifications you have successfully received.
Pull Organizational Notifications
Notifications for the authenticated member’s organizations can be queried using a criteria finder. Notifications are retained and available to pull for 60 days.
We recommend using this API only to bootstrap initial notifications for your product launch and for error handling. Using Webhook Notifications is the recommended approach for getting updates from an organization’s feed.
Notification Schema
| Field | Type | Description |
|---|---|---|
| notificationId | long | Global unique identifier to ensure notification uniqueness. |
| organizationalEntity | Urn | The Organization Urn for which the notification belongs. |
| action | String | Action type that triggered the notification. Possible values:
|
| sourcePost | Urn | The activity or article Urn that the member acted on, e.g. the activity that member liked, the article that member shared. |
| lastModifiedAt | long | Timestamp of the last modification of the notification. |
| generatedActivity | Urn | An activity or comment Urn as a result of acting on the target, e.g. a comment entity generated when a member commented on an activity, article, etc. It exists for COMMENT, ADMIN_COMMENT, COMMENT_EDIT, COMMENT_DELETE, and SHARE_MENTION. |
Query Notifications Based on Criteria
Query Parameters
| Field | Description | Type | Required |
|---|---|---|---|
| organizationalEntity | The Organization Urn for which to query notifications. The authenticated member must be an administrator of the organization. | Urn | Yes |
| actions | Action type that triggered the notification. Possible values:
|
String[] | Yes |
| timeRange.start | Represents the inclusive (greater than or equal to) value in which to start the range. | long | No |
| timeRange.end | Represents the exclusive (strictly less than) value in which to end the range. | long | No |
| sourcePost | Activity Urn to search by. When this value is specified, only one enum can be specified in the actions parameter. | Urn | No |
Sample Request
Sample Response
{
"elements": [
{
"generatedActivity": "urn:li:share:6441333333905633322",
"lastModifiedAt": 1535741320050,
"notificationId": 4406044,
"sourcePost": "urn:li:activity:92828282828282828828",
"action": "SHARE_MENTION",
"organizationalEntity": "urn:li:organization:12345"
},
{
"generatedActivity": "urn:li:share:6343443434841538048",
"lastModifiedAt": 1535741251282,
"notificationId": 4406005,
"sourcePost": "urn:li:activity:29292929292992929292",
"action": "SHARE",
"organizationalEntity": "urn:li:organization:12345"
}
],
"paging": {
"count": 10,
"start": 0,
"links": [
{
"href": "/organizationalEntityNotifications?q=criteria&start=10&count=10&organizationalEntity=urn%3Ali%3Aorganization%3A12345",
"type": "application/json",
"rel": "next"
}
]
}
}
Note
All URNs must be URL encoded in order to use Restli Protocol 2.0.0. Example: <https://api.linkedin.com/rest/organizationalEntityNotifications?q=criteria&actions=List(COMMENT,SHARE_MENTION)&organizationalEntity=urn%3Ali%3Aorganization%3A12345>
Note
All URNs must be URL encoded in order to use Restli Protocol 2.0.0. Example: <https://api.linkedin.com/v2/organizationalEntityNotifications?q=criteria&actions=List(COMMENT,SHARE_MENTION)&organizationalEntity=urn%3Ali%3Aorganization%3A12345>