Create a subscription with the Notification API

This is for:

System Administrator
In this article

You can create a subscription in a Coveo organization to be notified whenever an activity that matches a certain pattern is triggered in this organization. There are two distinct levels of subscription you can create, assuming that you have the required privileges in the target Coveo organization: user subscriptions and administrator subscriptions. The main difference between the two is that a user subscription can only send user-friendly, formatted email notifications, whereas an administrator subscription can also send raw JSON data as an email, or as the body of a POST request against a URL specified in the subscription configuration.

Use the Create a subscription for the current member operation to create a user subscription, or use the Create a subscription operation to create an administrator subscription.

Request template

POST https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/subscriptions HTTP/1.1

or

POST https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/subscriptions/me HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyOAuth2Token>

Payload

{
  "name": <MySubscriptionDisplayName>,
  "type": <"EMAIL"|"EMAIL_JSON"|"WEB_HOOK">,
  "frequency": <"LIVE"|"HOURLY"|"DAILY"|"WEEKLY">,
  "parameters": {
    "emailRecipients": [
      <EmailAddress>
    ],
    "emailSubject": <MyEmailNotificationSubject>,
    "fromDisplayName": <MyEmailNotificationSenderName>,
    "serviceUrl": <MyWebHookNotificationServiceURL>
  },
  "pattern": {
    "content": {
      <MyActivityEventContentKeyValue>*
    },
    "resourceTypes": [
      <MyResourceType>*
    ],
    "operations: [
      <MyOperation>*
    ],
    "resultTypes": [
      <"SUCCESS"|"ERROR"|"ABORT">*
    ]
  },
  "description": <MySubscriptionDescription>,
  "enabled": <true|false>
}

Use the https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/subscriptions request path to create an administrator subscription.

Use the https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/subscriptions/me request path to create a user subscription.

In the selected request path:

In the Authorization HTTP header:

  • If you’re creating an administrator subscription:

    • Replace <MyOAuth2Token> by a Coveo access token that grants you the privilege to edit notifications (that is, the Edit access level on the Notifications domain) in the target Coveo organization (see Manage privileges and Notifications Domain).

  • If you’re creating a user subscription:

    • Replace <MyOAuth2Token> by a Coveo access token that grants you the privilege to view activities (that is, the View access level on the Activities domain) in the target Coveo organization (see Manage privileges and Activities Domain).

See:

It’s impossible to authenticate either of these calls using an API key, since the Privilege API needs to be able to retrieve an email address from the access token in order to register the new subscription.

In the request body:

  • Set the name property to the string you want to use as a display name for your subscription in the Coveo Administration Console (for example, "Source refresh error web hook").

  • Set the type property to the value that best corresponds to the way you want the service to send notifications for your subscription. Possible values are:

    • "EMAIL": Send user friendly, HTML formatted emails whose content includes only the most vital activity event information.

    • "EMAIL_JSON": Send un-formatted emails whose content includes the entire activity event data.

    • "WEB_HOOK": Send HTTP POST requests to the URL you specify as the serviceUrl property value of the parameters object. The body of those requests is the activity event data. The connection timeouts after 5 seconds, and the response is basically ignored by the service (that is, if the HTTP request fails, it’s not retried).

    User subscriptions must have "EMAIL" as their type.

    The "EMAIL_JSON" and "WEB_HOOK" type values are only available for administrator subscriptions.

  • Set the frequency property to the string that best corresponds to the frequency at which you want the service to send notifications for your subscription. Possible values are:

    • "LIVE": Send a notification as soon as possible when a matching activity event occurs.

    • "HOURLY", "DAILY", and "WEEKLY": Send periodical notifications including all matching activity events that occurred during the corresponding time interval.

      You can’t set the frequency property to "HOURLY", "DAILY", or "WEEKLY" if your subscription type is "WEB_HOOK".

  • In the parameters object:

    • If the type property of your subscription is either "EMAIL" or "EMAIL_JSON":

      • In the emailRecipients array, enter the email address of the notification recipient (for example, "jsmith@example.com"). Only one recipient is allowed.

      • Optionally, set the emailSubject property to a string that indicates the email subject to use when sending your subscription notifications (for example, "Warning - Source refresh error occurred").

      • Optionally, set the fromDisplayName property to a string that indicates the sender name to use when sending your subscription notifications (for example, "My Coveo Organization").

    Otherwise, you don’t need to include the emailSubject or fromDisplayName properties at all.

    • If the type property of your subscription is "WEB_HOOK":

      • Set the serviceUrl property to the string that corresponds to the URL where your subscription should send its HTTP POST requests (for example, "http://wwww.example.com/myendpoint").

      Otherwise, you don’t need to include the serviceUrl property at all.

  • In the pattern object:

    • In the resourceTypes array, for each activity resource type you want to subscribe to, include the corresponding string (see ResourceTypes Array).

    • In the operations array, for each activity operation you want to subscribe to for the specified resourceTypes, include the corresponding string (see Operations Array).

    • In the resultTypes array, for each activity result type you want to subscribe to for the specified operations and resourceTypes, include the corresponding string. Possible values are: "SUCCESS", "ERROR", and "ABORT".

    Instead of explicitly specifying constant string values, you can use the wildcard operator (*) in any of the pattern object array properties (resourceTypes, operations, and/or resultTypes) to indicate that you want your subscription to send notifications for activity events that match any resource type, operation, and/or result type.

  • Optionally, in the content object, replace <MyActivityEventContent>* by any number activity event content key-value pairs to use as additional filters for your subscription (e.g, "sourceId": "mycoveocloudv2organization-rp5rxzbdz753uhndklv2ztkfgy").

The content object property is an advanced subscription feature that’s essentially exposed for internal use by Coveo.

One way for you to retrieve a list of content keys which are usable as filters for activity events that match a specific resource type, operation, and result type combination is to use the Activity API to get a similar event (assuming that such an event exists in the activity logs of your Coveo organization). In the body of a successful response, you can look for the content property of any matching item to find which keys you can use to further refine your subscription pattern.

  • Optionally, set the description property to a string that clearly explains the purpose of your subscription (for example, "Sends a POST HTTP request to http://www.example.com/myendpoint when a refresh operation fails on a specific source.").

    Although doing so is optional, you should generally provide a relevant value for the description property.

  • Set the enabled property to true if you want your subscription to take effect immediately after it has been created. Set this property to false if you want to temporarily disable your subscription.

    The enabled property is set to true by default.

The body of a successful response (201 Created) contains information about the newly created subscription, including its unique idproperty and status object.

You can refer to the id property of a subscription to later modify or delete this subscription.

The status object contains the following properties:

  • healthIndicator: A string that gives a general indication of how well the subscription is doing. Possible values are:

    • UNKNOWN: Indicates that no statistics are available for the subscription, either because the subscription has not yet triggered any notifications, or because it has not triggered any notifications for a while, and the service has since deleted its statistics. This is the default healthIndicator value when you create a new subscription.

    • GOOD: Indicates that a very low percentage (for example, less than 5%) of the notifications triggered by the subscription are failures, errors, or cancellations.

    • WARNING: Indicates that a relatively low, but still significant percentage (for example, between 5% and 20%) of the notifications triggered by the subscription are failures, errors, or cancellations.

    • PROBLEMATIC: Indicates that a relatively high percentage (for example, 20% or more) of the notifications triggered by the subscription are failures, errors, or cancellations.

  • statistics: An object that contains the three following properties:

    • numberOfSuccess: The number notifications that were successfully processed, sent and received for this subscription.

    • numberOfFailures: The number of notifications that were successfully processed, sent, but not successfully received for this subscription (that is, the number of errors on the client side).

    • numberOfErrors: The number of notifications that were not successfully processed for this subscription (that is, the number of errors on the Notification API side).

    • numberOfCancellations: The number of notifications that were successfully processed, but were intentionally not sent by the Notification API (for example, because the daily notification limit had been reached in the target Coveo organization).

Sample requests

Creating an administrator subscription

POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/subscriptions HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "name": "Webhook on successful indexing pipeline extension creation",
  "type": "WEB_HOOK",
  "frequency": "LIVE",
  "parameters": {
    "serviceUrl": "http://www.example.com/myendpoint"
  },
  "pattern": {
    "content": {},
    "resourceTypes": [
      "EXTENSION"
    ],
    "operations": [
      "CREATE"
    ],
    "resultTypes": [
      "SUCCESS"
    ]
  },
  "description": "Sends an HTTP POST request to http://www.example.com/myendpoint whenever an indexing pipeline extension is successfully created in the organization.",
  "enabled": true
}

Successful response - 201 Created

{
  "enabled": true,
  "name": "Webhook on successful extension creation",
  "description": "Sends an HTTP POST request to http://www.example.com/myendpoint whenever an indexing pipeline extension is successfully created in the organization.",
  "pattern": {
    "content": {},
    "operations": [
      "CREATE"
    ],
    "resourceTypes": [
      "EXTENSION"
    ],
    "resultTypes": [
      "SUCCESS"
    ]
  },
  "type": "WEB_HOOK",
  "frequency": "LIVE",
  "parameters": {
    "emailRecipients": [],
    "serviceUrl": "http://www.example.com/myendpoint"
  },
  "id": "sg4omxc7hrnfmj37x6augpsmbu",
  "organizationId": "mycoveocloudv2organizationg8tp8wu3",
  "status": {
    "healthIndicator": "UNKNOWN",
    "statistics": {
      "numberOfSuccess": 0,
      "numberOfFailures": 0,
      "numberOfErrors": 0,
      "numberOfCancellations": 0
    }
  }
}

Creating a user subscription

POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/subscriptions/me HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "name": "Live source rebuild failure report",
  "type": "EMAIL",
  "frequency": "LIVE",
  "parameters": {
    "emailRecipients": [
      "asmith@example.com"
    ],
    "fromDisplayName": "mycoveocloudv2organizationg8tp8wu3",
    "emailSubject": "Warning - Source rebuild failed"
  },
  "pattern": {
    "resourceTypes": [
      "SOURCE"
    ],
    "operations: [
      "REBUILD"
    ],
    "resultTypes": [
      "ERROR"
    ]
  },
  "description": "Sends a user-friendly email report to the user who created the subscription whenever a source rebuild fails in the organization.",
  "enabled": true
}

Successful response - 201 Created

{
  "enabled": true,
  "name": "Live source rebuild failure report",
  "description": "Sends a user-friendly email report to the user who created the subscription whenever a source rebuild fails in the organization.",
  "pattern": {
    "content": {},
    "operations": [
      "REBUILD"
    ],
    "resourceTypes": [
      "SOURCE"
    ],
    "resultTypes": [
      "ERROR"
    ]
  },
  "type": "EMAIL",
  "frequency": "LIVE",
  "parameters": {
    "emailRecipients": [
      "asmith@example.com"
    ],
    "fromDisplayName": "mycoveocloudv2organizationg8tp8wu3",
    "emailSubject": "Warning - Source rebuild failed"
  },
  "id": "woyqurk4cftiwae5uyqx3jkpru",
  "organizationId": "mycoveocloudv2organizationg8tp8wu3",
  "userId": "asmith@example.com-google",
  "status": {
    "healthIndicator": "UNKNOWN",
    "statistics": {
      "numberOfSuccess": 0,
      "numberOfFailures": 0,
      "numberOfErrors": 0,
      "numberOfCancellations": 0
    }
  }
}