Notifications

Every time a document is created, modified, or deleted in CDS, CDS will send one (or more) notifications out to listening clients. Clients can subscribe to these notifications, and take action based on their content.

Notifications Diagram

To get started with CDS notifications, see the links below.

Notification Failure & Retries

Notifications that are sent to clients can fail - there might be a general network glitch or the client might be down. The CDS will retry sending the request for up to 1 hour with an exponential back off. This means CDS will immediately try once, if that fails, CDS will wait 5 seconds, then steadily increase the wait time between tries up to 5 minutes, then try again up to an hour. If this policy cannot work with your system’s requirements, please talk to NPR Member Partnership.

Subscribing to Notifications

Clients that wish to subscribe to CDS document change notifications should first ensure their application has a webhook endpoint that is capable of handling the notification request. This endpoint should:

  • Be publicly accessible on the Internet
  • Be capable of handling (and responding to) a POST request from CDS

In addition, your client should already have a CDS Authorization token that will be used for subscribing to notifications. If you don’t already have one, reach out!

The Subscription Flow

Step 1: Implement a Webhook

In order to receive notifications, clients must implement a webhook that is capable of both confirming the subscription to CDS document events, and processing notifications as they come through.

For information on how to implement this webhook for your client, see the webhook documentation.

Step 2: Email NPR

For stations that would like to be subscribed to CDS notifications, email Member Partnership. Please provide the following information:

Once we receive your request, we’ll get back to you with a time that we can turn on notifications for your client.

Step 3: CDS sends a confirmation message

When NPR sets up notifications for your client, CDS will send a confirmation message to the webhook you’ve provided. That message will be a JSON-encoded message containing a Type attribute with the value SubscriptionConfirmation:

{
  "Type": "SubscriptionConfirmation",
  ...
}

Confirmation messages should be responded to within five minutes.

When your client receives this message, it should forward the body verbatim to the CDS subscription endpoint. CDS will respond with a 200, indicating the subscription is confirmed.

For more information on how subscription confirmation message handling, see the webhook documentation.

Step 4: Notifications flow as normal!

Your client will begin to receive POST requests from CDS containing notifications of document creations, deletions, and updates.

How to unsubscribe

In order to unsubscribe, email Member Partnership with your subscription details.

The webhook

In order to subscribe to CDS document notifications, clients must implement a webhook that can perform the following functions:

Subscription Confirmation

When NPR sets up notifications for your client, CDS will send a confirmation message to the webhook you’ve provided. That request will be a POST request, and the body will be a JSON-encoded message containing a Type attribute with the value SubscriptionConfirmation along with additional information:

{
  "Type": "SubscriptionConfirmation",
  ...
}

NOTE: Confirmation messages contain a Type attribute (capitalized); all other notifications contain a type attribute (all lowercase).

When a client receives this message, it should send a POST request to the CDS subscription endpoint. The body of this post request should be exactly the body that was received in the confirmation request; no alterations should be made. This endpoint requires authorization.

CDS will respond with a 200, indicating the subscription is confirmed.

Subscription confirmation step 1

Subscription confirmation step 2

Processing Notifications

Once the subscription is confirmed, CDS will begin sending notifications to the webhook provided. These notifications will all be POST requests, and the bodies will all represent document create/update/delete events from CDS. For more information on the notifications themselves, see the payloads documentation.

Notification payloads

There are three types of notification payloads that can be sent by CDS:

Every notification will always contain the following attributes:

Attribute Type Description
type String The type of this notification. This will always be document.created, document.updated, or document.deleted
documentId String The ID of the document affected
documentUrl URL A link to retrieve this document (note: in the case of deleted documents, this link may return a 404) 
{
  "type": "document.created",
  "documentId": 12345,
  "documentUrl": "https://content.api.npr.org/v1/documents/12345"
}

Based on the type of notification, there may be additional information in the notification. See each notification page or the below links for more details.

Created notification

When a document is newly published, a “created” notification is sent for it. This notification will not have any “prior document” information.

A “created” notification will have the following attributes:

Attribute Type Guaranteed present? Description
type string Yes The type of the event; for a “created” event, this will be document.created
documentId string Yes The ID of the newly-created document
documentUrl string Yes The absolute URL of the newly-created document

Example 

{
  "type": "document.created",
  "documentId": "1002",
  "documentUrl": "https://content.api.npr.org/v1/documents/1002"
}

Deleted notification

When an existing document is deleted, a “deleted” notification is sent. This notification will have “prior document” information contained in it.

A “deleted” notification will have the following attributes:

Attribute Type Description
type string The type of the event; for a “deleted” event, this will be document.deleted
documentId string The ID of the deleted document
documentUrl string The absolute URL of the deleted document (note that this URL will likely return a 404 at this point)
priorDocumentUrl string A URL at which the full prior document can be retrieved. This URL is valid for 24 hours after the deletion itself.
partialPriorDocument object A trimmed-down version of the prior document; for more info, see the prior document page

Example 

{
  "type": "document.deleted",
  "documentId": "1000",
  "documentUrl": "https://content.api.npr.org/v1/documents/1000",
  "priorDocumentUrl": "https://cds-prior-documents.npr.org/000000-0000-0000-000000",
  "partialPriorDocument": {
    "collections": [
      {
        "href": "/v1/documents/1234",
        "rels": [
          "podcast-channel"
        ]
      },
      {
        "href": "/v1/documents/5678",
        "rels": [
          "topic"
        ]
      }
    ],
    "nprWebsitePath": "/1000/2022/02/25/hes-back-superman-returns-to-earth"
  }
}

Prior document information

When a document is deleted or updated, the notification sent will have “prior document” information; essentially, this is information representing the document prior to deletion or modification. This is represented in two ways: the partialPriorDocument object, and the priorDocumentUrl link.

Prior document URL

The priorDocumentUrl is a URL at which the prior document is available for retrieval in its entirety by clients. This URL is valid for 24 hours, after which the prior document will no longer be available.

Note that you only need to do a simple “GET” with no authentication to see the prior document. S3 will reject the request if you try and use the same authentication you do for the CDS.

"priorDocumentUrl": "https://cds-prior-document-host.npr.org/00000-0000-0000-000000"

Partial prior document

The partialPriorDocument object contains a small portion of the prior document. This partial document allows clients to take action without necessarily pulling the entire document from the priorDocumentUrl.

The following attributes will be place into the partialPriorDocument object, but only if they were originally present on the prior document. So, if a prior document had no nprWebsitePath, for example, that attribute would not be present in the partialPriorDocument object.

Attribute Profile
collections publishable profile
nprWebsitePath renderable profile 
"partialPriorDocument": {
  "collections": [
    {
      "href": "/v1/documents/12345",
      "rels": [
        "topic"
      ]
    },
    {
      "href": "/v1/documents/67890",
      "rels": [
        "podcast-channel"
      ]
    }
  ],
  "nprWebsitePath": "/2022/05/27/12345670/firefly-class-craft-deemed-unsafe"
}

Filters

When subscribing to CDS notifications, clients may choose to receive only a subset of notifications sent by CDS. This subset is controlled by filters, chosen when a client intially subscribes to CDS.

Currently, notifications can only be filtered by profile.

Profile Filters

When a client provides a set of profiles to filter by, they are indicating that they wish to only receive notifications affecting those particular profiles. All other notifications will not be sent to the client.

For example, say the client wishes to filter by the profiles has-audio, podcast-episode, and listenable. Any notification concerning a document containing any of those profiles at the top level will be sent to the client; all others will be filtered out.

Prior Document Profiles

Filters apply to the profiles of both the current document and the prior document. In practice, this means notifications will be sent for all the following cases:

  • If a document is created with the client’s configured profiles
  • If a document is updated and it has a configured profile
  • If a document is updated and a configured profile is added
  • If a document is updated and a configured profile is removed
  • If a document is deleted and it had a configured profile

Examples

Let’s say a client is filtering by has-audio, podcast-episode, and listenable.

  • A document is created with the following profiles:
  • A notification WILL be sent to the client, because it is filtering for has-audio.
  • A document is created with the following profiles:
  • A notification WILL NOT be sent to the client, because it has none of the configured profiles.
  • A document is with the following profiles is deleted:
  • A notification WILL be sent to the client, because it is filtering for has-audio.
  • A document with the following profiles is deleted:
  • A notification WILL NOT be sent to the client, because it has none of the configured profiles.
  • A document with the following profiles is updated; its profiles are unchanged:
  • A notification WILL be sent to the client, because it is filtering for has-audio.
  • A document with the following profiles is updated:
  • The has-audio profile is added.
  • A notification WILL be sent to the client, because it is filtering for has-audio.

Extension Links

The majority of creation, deletion, and update events in CDS will result in exactly one notification being sent for the event. The exception is for extension links; when two documents are linked via an extension link, additional notifications will be sent for linked documents (unless filtered by the client’s profile filters).

For more information, see the page on Extension Links.

Table of contents

© 2024 npr