Skip to main content
With subscribe actions, you’ll receive near-instant webhooks as events occur in your customers’ SaaS applications. This enables your application to quickly react to events such as record creation, deletion, and field updates.
Please note that:
  • Subscribe actions are supported for a subset of providers. See the provider guides to check whether your provider supports subscribe actions and whether any additional setup is required.
  • Subscribe actions do not produce Operations or Logs that can be viewed in the Ampersand dashboard.
  • It takes 1-2 minutes, and occasionally up to 10 minutes, for the first events to arrive after the initial installation.

​
Defining subscriptions

To subscribe to an object, you need to specify:
  • objectName: to indicate which object you’d like to subscribe to. This should match the name of the object in the official documentation for the SaaS API.
  • destination: the name of the destination that you’ve defined
  • inheritFieldsAndMapping: required when using createEvent, updateEvent, deleteEvent, or associationChangeEvent. Set this to true so the subscribe action inherits the mapped and unmapped fields from the matching Read Action. true is currently the only supported value. Learn more in Fields and mapping.
You then need to specify the particular events you want to subscribe to. We support the following events:
  • createEvent: triggers when a new record is created in the SaaS application.
  • updateEvent: triggers when any existing record is modified. The watchFieldsAuto: all setting ensures that you subscribe to all field changes. Alternatively, you can list specific fields to watch in requiredWatchFields. Note: Only one of requiredWatchFields or watchFieldsAuto should be provided.
  • deleteEvent: triggers when a record is removed from the system.
  • associationChangeEvent: triggers when a record’s associations have been modified. This is only supported for HubSpot. Please see Association changes.
  • otherEvents: gives you the ability that listen to any other events that are available in the provide API that Ampersand doesn’t natively support. Please see Other Events.

​
Specify fields to watch

You can provide fields to watch for update events and specify them in a list. Note: Only one of requiredWatchFields or watchFieldsAuto should be provided. Here is an example amp.yaml
For an example of a webhook message delivered according to the above amp.yaml, please see Subscribe action webhooks.

​
Association changes

In HubSpot, association changes do not trigger update events, you must subscribe to them specifically using associationChangeEvent. On the other hand, in Salesforce, you can subscribe to fields that refer to associations (e.g. You can subscribe to update events on the accountid field of contacts). HubSpot example:
Salesforce example:

​
Other events

Beyond the standard events that Ampersand supports, you have the ability to subscribe to any other event that that underlying platform supports. The event names listed in otherEvents must match the provider’s raw event names exactly. For Salesforce this includes events like:
  • UNDELETE
For HubSpot, this includes events like:
  • {OBJECT_NAME}.restore (e.g. contact.restore)
  • {OBJECT_NAME}.merge (e.g. contact.merge)
To listen to these other events, add an otherEvents array to the subscribed object in your amp.yaml. If an object is subscribing only to otherEvents (no createEvent, updateEvent, or deleteEvent), it does not need its own matching entry in the read block, and inheritFieldsAndMapping is not required for that object. The read block itself must still exist on the integration. In the example below, the customers object uses create/update/delete events and therefore must have a matching read object with inheritFieldsAndMapping: true. The job.appointments object subscribes only to otherEvents and has no matching read entry:
You can also combine otherEvents with standard events on the same object. In this Salesforce example, the account object subscribes to both createEvent and the non-standard UNDELETE event. Because it uses createEvent, it requires a matching read entry and inheritFieldsAndMapping: true:

​
Specify backfill behavior

By combining subscribe actions with read actions, you can get a full picture of all the data in your customer’s SaaS instance. You can:
  • Do a full backfill when the user first installs the integration to get historic data.
  • Then, receive real-time updates about changes in their SaaS instance
Here is an example amp.yaml:
If you do not wish to do a backfill when the integration is first installed, you can omit the backfill block in the read action definition. Because there aren’t any schedules or backfills defined, the read action won’t actually do anything but its fields and mappings will be used by the subscribe action.

​
Fields and mapping

Your read action’s set of fields and field mappings will apply to the subscribe action. When we deliver you the webhook, it will contain fields and mappedFields based on the fields and mapped fields from your read action. You can learn more in Object and field mapping.

​
Receiving data

You will receive messages about events happening in your customer’s SaaS instance. These look very similar to the messages for read actions. See Subscribe action webhooks for more information.