--- title: Create a subscription with the Notification API slug: '36' canonical_url: https://docs.coveo.com/en/36/ collection: manage-an-organization source_format: adoc --- # Create a subscription with the Notification API You can create a _subscription_ in a [Coveo organization](https://docs.coveo.com/en/185/) to be notified whenever an [activity](https://docs.coveo.com/en/173/) that matches a certain pattern is triggered in this organization. There are two distinct levels of [subscription](https://docs.coveo.com/en/248/) you can create, assuming that you have the required [privileges](https://docs.coveo.com/en/228/) 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](https://docs.coveo.com/en/221/), 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](https://platform.cloud.coveo.com/docs?urls.primaryName=Notification#/Subscription/rest_organizations_paramId_subscriptions_me_post) operation to create a user subscription, or use the [Create a subscription](https://platform.cloud.coveo.com/docs?urls.primaryName=Notification#/Subscription/rest_organizations_paramId_subscriptions_post) operation to create an administrator subscription. **Request template** ```http POST https://platform.cloud.coveo.com/rest/organizations//subscriptions HTTP/1.1 ``` or ```http POST https://platform.cloud.coveo.com/rest/organizations//subscriptions/me HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer ``` Payload ```json { "name": , "type": <"EMAIL"|"EMAIL_JSON"|"WEB_HOOK">, "frequency": <"LIVE"|"HOURLY"|"DAILY"|"WEEKLY">, "parameters": { "emailRecipients": [ ], "emailSubject": , "fromDisplayName": , "serviceUrl": }, "pattern": { "content": { * }, "resourceTypes": [ * ], "operations: [ * ], "resultTypes": [ <"SUCCESS"|"ERROR"|"ABORT">* ] }, "description": , "enabled": } ``` Use the `+https://platform.cloud.coveo.com/rest/organizations//subscriptions+` request path to create an administrator subscription. Use the `+https://platform.cloud.coveo.com/rest/organizations//subscriptions/me+` request path to create a user subscription. In the selected request path, replace `` with the [ID of the target Coveo organization](https://docs.coveo.com/en/148/). In the `Authorization` HTTP header: * If you're creating an administrator subscription: ** Replace `` by a Coveo access token that grants you the [privilege to edit notifications](https://docs.coveo.com/en/3151/) (that is, the **Edit** access level on the [**Notifications** domain](https://docs.coveo.com/en/1707#notifications-domain)) in the target Coveo organization. * If you're creating a user subscription: ** Replace `` by a Coveo access token that grants you the [privilege to view activities](https://docs.coveo.com/en/3151/) (that is, the **View** access level on the [**Activities** domain](https://docs.coveo.com/en/1707#activities-domain)) in the target Coveo organization. See: * [Get your Coveo access token](https://docs.coveo.com/en/123/). * [Get the privileges of an access token](https://docs.coveo.com/en/109/). > **Note** > > 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](https://docs.coveo.com/en/183/) (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). -- > **Important** > > 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. > **Important** > > 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"`). ** 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"+`). * In the `pattern` object: -- ** In the [`resourceTypes` array](https://docs.coveo.com/en/1660#resourcetypes-array), for each activity resource type you want to subscribe to, include the corresponding string. ** In the [`operations` array](https://docs.coveo.com/en/1660#operations-array), for each activity operation you want to subscribe to for the specified `resourceTypes`, include the corresponding string. ** 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"`. -- > **Note** > > 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 `*` by any number activity event `content` key-value pairs to use as additional filters for your subscription (e.g, `"sourceId": "mycoveocloudv2organization-rp5rxzbdz753uhndklv2ztkfgy"`). > **Note** > > 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."+`). > **Leading practice** > > 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` to temporarily disable your subscription. > **Note** > > 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 ``id``property 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 request 1 **Creating an administrator subscription** ```http POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/subscriptions HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer **********-****-****-****-************ ``` Payload ```json { "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** ```json { "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 } } } ``` ## Sample request 2 **Creating a user subscription** ```http POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/subscriptions/me HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer **********-****-****-****-************ ``` Payload ```json { "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** ```json { "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 } } } ```