# Using Amazon DocumentDB event subscriptions
<a name="event-subscriptions"></a>

Amazon DocumentDB uses Amazon Simple Notification Service (Amazon SNS) to provide notifications when an Amazon DocumentDB event occurs. These notifications can be in any form that is supported by Amazon SNS for an AWS Region, such as an email, a text message, or a call to an HTTP endpoint.

Amazon DocumentDB groups these events into categories that you can subscribe to so that you can be notified when an event in that category occurs. You can subscribe to an event category for an instance, cluster, snapshot, cluster snapshot, or for a parameter group. For example, if you subscribe to the Backup category for a given instance, you are notified whenever a backup-related event occurs that affects the instance. You also receive notification when an event subscription changes.

Events occur at both the cluster and the instance level, so you can receive events if you subscribe to a cluster or an instance.

Event subscriptions are sent to the addresses you provide when you create the subscription. You might want to create several different subscriptions, such as a subscription that receives all event notifications and another subscription that includes only critical events for your production instances. You can easily turn off notification without deleting a subscription. To do so, set the **Enabled** radio button to **No** in the Amazon DocumentDB console.

**Important**  
Amazon DocumentDB doesn't guarantee the order of events sent in an event stream. The event order is subject to change.

Amazon DocumentDB uses the Amazon Resource Name (ARN) of an Amazon SNS topic to identify each subscription. The Amazon DocumentDB console creates the ARN for you when you create the subscription.

Billing for Amazon DocumentDB event subscriptions is through Amazon SNS. Amazon SNS fees apply when using event notification. For more information, see Amazon Simple Notification Service Pricing. Other than Amazon SNS charges, Amazon DocumentDB does not bill for event subscriptions. 

**Topics**
+ [Subscribing to events](event-subscriptions.subscribe.md)
+ [Manage subscriptions](event-subscriptions.managing.md)
+ [Categories and messages](event-subscriptions.categories-messages.md)

# Subscribing to Amazon DocumentDB events
<a name="event-subscriptions.subscribe"></a>

You can use the Amazon DocumentDB console to subscribe to event subscriptions, as follows:

1. Sign in to the AWS Management Console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).

1. In the navigation pane, choose **Event subscriptions**.  
![\[Amazon DocumentDB console navigation pane with Event Subscriptions option highlighted.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/subscribe-event-subs.png)

1. In the **Event subscriptions** pane, choose **Create event subscription**.  
![\[Event Subscriptions pane highlighting the Create event subscription button in the upper-right corner.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/subscribe-create.png)

1. In the **Create event subscription** dialog box, do the following:
   + For **Name**, enter a name for the event notification subscription.   
![\[The Create event subscription form showing the Details section and the Name input field.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/subscribe-name.png)
   + For **Target**, choose where you want to send notifications to. You can choose an existing **ARN** or choose **New Email Topic** to enter the name of a topic and a list of recipients.   
![\[The Target section with options to specify where to send notifications to.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/subscribe-target.png)
   + For **Source**, choose a source type. Depending on the source type you selected, choose the event categories and the sources that you want to receive event notifications from.  
![\[The Source section to select a source type to receive event notifications from.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/subscribe-source.png)
   + Choose **Create**.  
![\[The Source section with the Create button in the lower-right corner.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/subscribe-create-2.png)

# Managing Amazon DocumentDB event notification subscriptions
<a name="event-subscriptions.managing"></a>

If you choose **Event subscriptions** in the navigation pane of the Amazon DocumentDB console, you can view subscription categories and a list of your current subscriptions. You can also modify or delete a specific subscription.

## To modify your current Amazon DocumentDB event notification subscriptions
<a name="event-subscriptions.modify"></a>

1. Sign in to the AWS Management Console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).

1. In the navigation pane, choose **Event subscriptions**. The **Event subscriptions** pane shows all your event notification subscriptions.   
![\[Amazon DocumentDB console navigation pane with Event Subscriptions option highlighted.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/modify-event-subs.png)

1. In the **Event subscriptions** pane, choose the subscription that you want to modify and choose **Edit**.  
![\[The Event subscriptions pane showing a selected subscription and the Edit button.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/modify-edit.png)

1. Make your changes to the subscription in either the **Target** or **Source** section. You can add or remove source identifiers by selecting or deselecting them in the Source section.   
![\[The Modify event subscription form highlighting the Target section.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/modify-target.png)

1. Choose **Modify**. The Amazon DocumentDB console indicates that the subscription is being modified.   
![\[The end of the Modify event subscription form with the Modify button highlighted.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/modify-button.png)

## Deleting an Amazon DocumentDB event notification subscription
<a name="event-subscriptions.delete"></a>

You can delete a subscription when you no longer need it. All subscribers to the topic will no longer receive event notifications specified by the subscription. 

1. Sign in to the AWS Management Console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).

1. In the navigation pane, choose **Event subscriptions**.   
![\[Amazon DocumentDB console navigation pane with Event Subscriptions option highlighted.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/delete-event-subs.png)

1. In the **Event subscriptions** pane, choose the subscription that you want to delete.   
![\[The Event subscriptions pane showing a selected subscription.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/delete-select.png)

1. Choose **Delete**.  
![\[The Event subscriptions pane highlighting the Delete button.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/delete-delete.png)

1. A pop-up window will appear asking you if you want to permanently delete this notification. Choose **Delete**.  
![\[A dialog box confirming deletion of the event subscription with the Delete button highlighted in the lower-right corner.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/event-subs/delete-delete-2.png)

# Amazon DocumentDB event categories and messages
<a name="event-subscriptions.categories-messages"></a>

Amazon DocumentDB generates a significant number of events in categories that you can subscribe to using the console. Each category applies to a source type, which can be an instance, cluster, snapshot, or parameter group.

**Note**  
Amazon DocumentDB uses existing Amazon RDS event definitions and IDs.

## Amazon DocumentDB events originating from instances
<a name="event-subscriptions.db-origin"></a>


| Category | Description | 
| --- | --- | 
| availability | The instance restarted. | 
| availability | The instance shutdown. | 
| configuration change | Applying modification to an instance class. | 
| configuration change | Finished applying modification to an instance class. | 
| configuration change | Reset primary credentials. | 
| creation | Instance created. | 
| deletion | Instance deleted | 
| failure | The instance has failed due to an incompatible configuration or an underlying storage issue. Begin a point-in-time-restore for the instance. | 
| notification | Instance stopped. | 
| notification | Instance started. | 
| notification | Instance is being started due to it exceeding the maximum allowed time being stopped. | 
| recovery | Recovery of the instance has started. Recovery time will vary with the amount of data to be recovered. | 
| recovery | Recovery of the instance is complete. | 
| security patching | The operating system update is available for your instance. For information about applying updates, see [Maintaining Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/db-instance-maintain.html). | 

## Amazon DocumentDB events originating from a cluster
<a name="event-subscriptions.cluster-origin"></a>


| Category | Description | 
| --- | --- | 
| creation | Cluster created | 
| deletion | Cluster deleted. | 
| failover | Promoting previous primary again. | 
| failover | Completed failover to instance. | 
| failover | Started failover to DB instance: %s | 
| failover | Started same AZ failover to DB instance: %s | 
| failover | Started cross AZ failover to DB instance: %s | 
| maintenance | Cluster has been patched. | 
| maintenance | Database cluster is in a state that cannot be upgraded: %s | 
| notification | The cluster stopped. | 
| notification | The cluster started. | 
| notification | The cluster stop failed. | 
| notification | The cluster is being started due to it exceeding the maximum allowed time being stopped.  | 
| notification | Renamed cluster from %s to %s. | 

## Amazon DocumentDB events originating from cluster snapshot
<a name="event-subscriptions.snapshot-origin"></a>

The following table shows the event category and a list of events when an Amazon DocumentDB cluster snapshot is the source type.


| Category | Description | 
| --- | --- | 
| backup | Creating manual cluster snapshot. | 
| backup | Manual cluster snapshot created. | 
| backup | Creating automated cluster snapshot. | 
| backup | Automated cluster snapshot created. | 

## Amazon DocumentDB events originating from parameter group
<a name="event-subscriptions.parameter"></a>

The following table shows the event category and a list of events when a parameter group is the source type. 


| Category | Description | 
| --- | --- | 
| configuration change | Updated parameter %s to %s with apply method %s |