Overview

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.

Notifications Diagram

Available events

Ampersand supports the following notification event types:

Installation lifecycle

• 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 operations

• 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
• read.triggered.done: Fires when an on-demand triggered read completes successfully
• read.triggered.error: Fires when an on-demand triggered read fails

Write operations

• write.async.done: Fires when an asynchronous write operation completes, indicating success or failure and which records were written or had errors

Subscribe

• subscribe.create.success: Fires when a subscription becomes active. For providers that Ampersand subscribes to programmatically, this is when the subscribe action is set up successfully; for providers whose webhooks are configured manually in the provider’s UI, this is when the first event is delivered
• subscribe.update.success: Fires when an update to an existing subscribe action completes successfully
• subscribe.delete.success: Fires when a subscribe action is removed successfully, including tearing down the subscription on the provider’s side
• subscribe.create.error: Fires when Ampersand fails to set up a subscribe action for an installation
• subscribe.update.error: Fires when Ampersand fails to update an existing subscribe action for an installation
• subscribe.delete.error: Fires when a subscribe action is removed but Ampersand could not tear down the subscription on the provider’s side, so it may still be active and continue to consume provider resources (for example, event or subscription quota). You may need to remove it manually in the provider

Connection

• connection.created: Fires when a new OAuth connection is established with a SaaS provider
• connection.refreshed: Fires when Ampersand automatically refreshes a connection’s OAuth access token as it nears expiry, using the connection’s refresh token. This happens with no user involvement and keeps the connection active
• connection.updated: Fires when an existing connection is updated, either when a user re-authenticates (for example, reconnecting to resolve an errored connection) or when the connection’s credentials or metadata are changed via the update connection API
• connection.deleted: Fires when a connection is deleted, such as through the dashboard or the delete connection API
• connection.error: Fires when there’s an error with an OAuth connection, such as authentication failures or token refresh issues

Destination

• destination.webhook.disabled: Fires when a webhook destination endpoint is disabled. This can happen automatically after repeated failed delivery attempts.

Setting up notifications

There are two ways to set up notifications:

• Using the Dashboard: Visual interface for quick setup
• Using the API: Programmatic setup for automation and integration

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, Slack, Kinesis or Amazon S3
     • 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.

1. Create a destination

POST https://api.withampersand.com/v1/projects/{projectIdOrName}/destinations
{
  "name": "production-alerts",
  "type": "webhook",
  "metadata": {
    "url": "https://your-webhook.com"
  }
}

2. Create a topic

POST https://api.withampersand.com/v1/projects/{projectIdOrName}/topics
{
  "name": "installation-events"
}

3. Create notification-event-topic routes

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"
}

4. Create topic-destination routes

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"
}