Skip to main content
Ampersand notifications deliver real-time messages about important lifecycle changes in your project. They allow you to track when customers install, update, or delete integrations; when backfills complete; and when sync issues occur. If you want to be notified when there are changes in your customer’s SaaS instances, use Subscribe Actions.

​
How notifications work

Notifications use topics to give you fine-grained control over which events reach which destinations. You can configure each topic to receive specific event types and route notifications to one or more destinations.
Notification Diagram

Notifications Diagram

​
Available events

Ampersand supports the following notification event types:
  • installation.created: Fires when a customer installs your integration to their SaaS instance
  • installation.updated: Fires when a customer modifies their integration configuration (e.g., changes field mappings)
  • installation.deleted: Fires when a customer uninstalls your integration from their SaaS instance
  • read.backfill.done: Fires when historical data sync completes so you know backfill data is ready to process
  • read.schedule.paused: Fires when a scheduled data sync is paused, often due to authentication issues or other errors
  • connection.created: Fires when a new OAuth connection is established with a SaaS provider

​
Setting up notifications

There are two ways to set up notifications:

​
Set up via Dashboard

  1. Create destinations
    • Go to Destinations
    • Click New Destination and configure:
      • Name: A descriptive name (e.g., “production-alerts”)
      • Type: Choose webhook, Kinesis, or log destination
      • Configuration: Provide the endpoint URL or stream details
    • Click Create Destination
  2. Create topics
    • Go to Notifications
    • Click New Topic
    • Configure your topic:
      • Name: A descriptive name (e.g., “installation-events”)
      • Event types: Select the events this topic should receive
      • Destinations: Select which destinations should receive notifications
    • Click Create Topic

​
Set up via API

When using the API, you need to create routes explicitly to connect events to topics and topics to destinations. The dashboard handles this automatically when you create a topic. See the API Reference for complete endpoint documentation. 
POST https://api.withampersand.com/v1/projects/{projectIdOrName}/destinations
{
  "name": "production-alerts",
  "type": "webhook",
  "metadata": {
    "url": "https://your-webhook.com"
  }
}

POST https://api.withampersand.com/v1/projects/{projectIdOrName}/topics
{
  "name": "installation-events"
}
Notification-Event-Topic Routes connect specific event types to topics. This determines which events are sent to each topic.
POST https://api.withampersand.com/v1/projects/{projectIdOrName}/notification-event-topic-routes
{
  "topicId": "your-topic-id",
  "eventType": "installation.created"
}
Topic-Destination Routes connect topics to destinations. This determines which destinations receive notifications for each topic.
POST https://api.withampersand.com/v1/projects/{projectIdOrName}/topic-destination-routes
{
  "topicId": "your-topic-id",
  "destinationId": "your-destination-id"
}