Subscribe actions

Get notified in near real time when a record is created, updated, or deleted in your customer’s SaaS, so your product can act right away. Instead of waiting for the next scheduled read, Ampersand delivers each change to your destination as it happens.

Subscribe actions work alongside read actions: a read can backfill your customer’s existing records, and a subscription keeps you up to date from then on.

Subscribe actions are supported for a subset of providers. See the provider guides to check whether your provider supports them. Some providers need setup in your provider app before events arrive: HubSpot, Gong, Housecall Pro, Gmail, and Zoho Mail.

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.

A subscribe action reuses the fields and mappings of a read action. So each object that uses createEvent, updateEvent, deleteEvent, or associationChangeEvent also needs an object with the same objectName under read. That read object doesn’t need a schedule or backfill: without them, it doesn’t read anything and only supplies the fields and mappings. Objects that only use otherEvents don’t need one.

In amp.yaml the setting is inheritFieldsAndMapping. In an installation’s config it’s spelled inheritFieldsAndMappings, with an s.

Events

Choose which events to subscribe to, and turn each one on with enabled: always (currently the only supported value):

Event	Fires when	Notes
createEvent	A record is created
updateEvent	A record is changed	Choose which field changes fire an event: list specific fields in requiredWatchFields, or set watchFieldsAuto to all (every field) or selected (the fields the customer selected for the read). Use one or the other.
deleteEvent	A record is deleted
associationChangeEvent	A record’s associations change	HubSpot only. See Association changes.
otherEvents	Any other event the provider sends	Use the provider’s raw event names. See Other events.

In this example, account gets create, update, and delete events, and update events fire only when one of three fields changes. The watched fields can be provider fields (phone) or mapped fields from the read action (notes, accountName):

specVersion: 1.0.0
integrations:
  - name: subscribeToSalesforce
    provider: salesforce
    subscribe:
      objects:
        - objectName: account
          destination: accountWebhook
          inheritFieldsAndMapping: true # for now this must be true
          createEvent:
            enabled: always
          updateEvent:
            enabled: always
            requiredWatchFields:
              - phone
              - notes # this is user-defined mapped field, from read action below.
              - accountName # this is a pre-defined mapped field, from read action below.
            # watchFieldsAuto: all # alternative to `requiredWatchFields` if you wish to watch all fields
          deleteEvent:
            enabled: always
    read: # Read action is required
      objects:
        - objectName: account
          mapToName: company
          destination: accountWebhook
          requiredFields:
            - fieldName: id
            - fieldName: name
              mapToName: accountName 
            - mapToName: notes
              mapToDisplayName: Notes
              prompt: These are notes that you would like to surface in our app.
          optionalFields:
            - fieldName: annualrevenue
            - fieldName: website

Association changes

In HubSpot, association changes don’t trigger update events, so subscribe to them with associationChangeEvent. Set includeFullRecords: true to also receive the associated record. In Salesforce, associations are fields on the record, so watch that field with updateEvent instead, like accountid on contacts.

HubSpot

specVersion: 1.0.0
integrations:
  - name: hubspotAssociation
    provider: hubspot
    subscribe:
      objects:
        - objectName: contacts
          destination: contactsWebhook
          inheritFieldsAndMapping: true
          associationChangeEvent:
            enabled: always
            # Whether we should retrieve the associated record
            includeFullRecords: true
    read: # Read action is required
      objects:
        - objectName: contacts
          destination: contactsWebhook
          ...

Salesforce

specVersion: 1.0.0
integrations:
  - name: salesforceAssociation
    provider: salesforce
    subscribe:
      objects:
        - objectName: contact
          destination: contactWebhook
          inheritFieldsAndMapping: true
          updateEvent:
            enabled: always
            requiredWatchFields:
              - accountid
    read: # Read action is required
      objects:
        - objectName: contact
          destination: contactWebhook
          ...

Other events

Beyond the standard events that Ampersand supports, you have the ability to subscribe to any other event that the 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, customers uses create, update, and delete events, so it has a matching read object and inheritFieldsAndMapping: true. job.appointments subscribes only to otherEvents, so it doesn’t need one:

specVersion: 1.0.0
integrations:
  - name: subscribeToHousecallPro
    provider: housecallPro
    read:
      objects:
        - objectName: customers
          destination: housecallProWebhook
          schedule: "*/10 * * * *"
          requiredFields:
            - fieldName: id
          optionalFieldsAuto: all
          backfill:
            defaultPeriod:
              days: 15
    subscribe:
      objects:
        - objectName: customers
          destination: housecallProWebhook
          inheritFieldsAndMapping: true
          createEvent:
            enabled: always
          updateEvent:
            enabled: always
            watchFieldsAuto: all
          deleteEvent:
            enabled: always

        - objectName: job.appointments # Only otherEvents — no matching read entry needed
          destination: housecallProWebhook
          otherEvents: # Must match the provider's raw event names exactly
            - job.appointment.scheduled
            - job.appointment.rescheduled
            - job.appointment.appointment_discarded
            - job.appointment.appointment_pros_assigned
            - job.appointment.appointment_pros_unassigned

You can also combine otherEvents with standard events on the same object, for example createEvent plus Salesforce’s UNDELETE. Because it uses a standard event, that object needs a matching read object and inheritFieldsAndMapping: true.

Combine with read actions

Pair a subscription with a read action to get the full picture: a backfill brings in your customer’s existing records when they install, and the subscription delivers every change after that. In this example, the read action backfills all accounts and supplies the fields and mappings, and the subscription sends each change:

specVersion: 1.0.0
integrations:
  - name: subscribeToSalesforce
    provider: salesforce
    subscribe:
      objects:
        - objectName: account
          destination: myWebhook
          inheritFieldsAndMapping: true
          createEvent:
            enabled: always
          updateEvent:
            enabled: always
            watchFieldsAuto: all
          deleteEvent:
            enabled: always
    read: # Read action is required
      objects:
        - objectName: account
          destination: myWebhook
          requiredFields:
            - fieldName: name
            - fieldName: billingcity
              mapToName: city
              mapToDisplayName: City
            - mapToName: country
              mapToDisplayName: Country
              prompt: Which field is the country for the account?
          # Read all existing accounts when the customer installs.
          # Leave out backfill if you only want changes from now on.
          backfill:
            defaultPeriod:
              fullHistory: true

If you only want changes from now on, leave out backfill (and schedule). The read object then doesn’t read anything; it only supplies the fields and mappings for the subscription.

What you receive

Each event is delivered to your destination with the fields and mappings from the matching read action, in fields and mappedFields. Each result also includes:

• subscribeEventType: the event type, normalized: create, update, delete, associationUpdate (HubSpot only), or other (for other events).
• providerEventType: the provider’s own event type.
• raw: the full record from the provider.
• rawEvent: the provider’s original event, when available.

Here’s an example message for the account subscription above. Learn more in Subscribe action webhooks and Object and field mapping.

{
  "action": "subscribe",
  "groupName": "Demo Group",
  "groupRef": "demo-group",
  "installationId": "692428b5-22b6-417d-9478-0375949223c0",
  "installationUpdateTime": "2025-03-21T04:20:16.872886Z",
  "objectName": "account",
  "projectId": "my-project-id",
  "provider": "salesforce",
  "result": [
    {
      "fields": { // Unmapped fields from read action
        "name": "Account ABC"
      },
      "mappedFields": { // Mapped fields from read action
        "city": "San Francisco",
        "country": "USA"
      },
      "subscribeEventType": "update",
      "providerEventType": "UPDATE",
      "raw": {
        "BillingCity": "San Francisco",
        "Id": "001Pa00000W4puRIAR",
        "Name": "Account ABC",
        "attributes": {
          "type": "Account",
          "url": "/services/data/v59.0/sobjects/Account/001Pa00000W4puRIAR"
        }
      },
      "rawEvent": {
        "ChangeEventHeader": {
          "changeOrigin": "com/salesforce/api/soap/63.0;client=SfdcInternalAPI/",
          "changeType": "UPDATE",
          "changedFields": [
            "Name",
            "LastModifiedDate"
          ],
          "commitNumber": 1742558812455698400,
          "commitTimestamp": 1742558812000,
          "commitUser": "005Do000000XDimIAG",
          "entityName": "Account",
          "recordId": "001Pa00000W4puRIAR",
          "sequenceNumber": 1,
          "transactionKey": "00004b85-ba97-e14f-68ca-cfa4c60f13ff"
        },
        "LastModifiedDate": "2025-03-21T12:06:52.000Z",
        "Name": "Account ABC"
      },
    }
  ],
  "resultInfo": {
    "numRecords": 1,
    "type": "inline"
  },
  "workspace": "customer-salesforce-subdomain"
}

Stop subscribe events

Subscribe actions don’t currently have a pause endpoint, so to stop events, turn them off in the config. Ampersand then updates the subscription in the provider, which usually takes 1–2 minutes and can take up to 10. Events that arrived before then may still be delivered.

For one customer

1. Find the customer’s installation ID, in the Ampersand Dashboard or with the List installations endpoint.

2. Call Update an installation with config.content.subscribe.objects.<objectName> in updateMask.

3. In the body, keep the object’s objectName, destination and inheritFieldsAndMappings, set createEvent, updateEvent and deleteEvent to never, and set otherEvents to an empty list:

   {
     "updateMask": ["config.content.subscribe.objects.contact"],
     "installation": {
       "config": {
         "content": {
           "subscribe": {
             "objects": {
               "contact": {
                 "objectName": "contact",
                 "destination": "contactWebhook",
                 "inheritFieldsAndMappings": true,
                 "createEvent": { "enabled": "never" },
                 "updateEvent": { "enabled": "never" },
                 "deleteEvent": { "enabled": "never" },
                 "otherEvents": []
               }
             }
           }
         }
       }
     }
   }
   

4. Check that it worked: after a few minutes, change a record of that object in the customer’s account. No event should arrive. Other installations aren’t affected.

Anything you leave out of the installation’s config falls back to amp.yaml. If the object isn’t in the config at all, for example because you replaced the subscribe objects without it, the customer keeps receiving its events. If you leave out otherEvents and amp.yaml lists some, like Salesforce UNDELETE, the subscription stays on. Keep the object in the config with every event turned off.

For Salesforce, turning every event off also removes the object from the org’s Change Data Capture channel, so it stops counting against the org’s event limits. Watching only some fields with requiredWatchFields doesn’t lower the count: Salesforce still counts an event for every change to the object.

Turn events back on

Call Update an installation for the same object again, with the events set to always:

{
  "updateMask": ["config.content.subscribe.objects.contact"],
  "installation": {
    "config": {
      "content": {
        "subscribe": {
          "objects": {
            "contact": {
              "objectName": "contact",
              "destination": "contactWebhook",
              "inheritFieldsAndMappings": true,
              "createEvent": { "enabled": "always" },
              "updateEvent": { "enabled": "always", "watchFieldsAuto": "all" },
              "deleteEvent": { "enabled": "always" }
            }
          }
        }
      }
    }
  }
}

Ampersand creates a new subscription, so you only receive changes made from then on. To catch up on changes made while events were off, trigger a read.

For every customer

Remove the object from subscribe in your amp.yaml and run amp deploy. Installations that have their own subscribe config for the object keep it.

When a customer uninstalls or revokes access

Deleting an installation also removes its subscriptions from the provider. Delete it before your customer disconnects or revokes Ampersand’s access: if the provider rejects Ampersand’s credentials, the subscription can’t be removed on the provider’s side.

Revoking Ampersand’s permissions or deactivating the connected user doesn’t stop events on its own. For Salesforce, the event channel stays in the customer’s org and keeps using its event limits until the subscription is removed.

Not receiving events?

Check that:

• Enough time has passed. The first events usually arrive 1–2 minutes after installation, and occasionally up to 10 minutes. For Salesforce, a new subscription can take 10–30 minutes to start delivering.
• Your provider app is set up. Some providers send events to Ampersand only after setup in your provider app, like HubSpot. The note at the top of this page lists the others.
• You’re changing records in the connected account. Events only come from the account your customer connected, so when testing, make your changes in that same account.
• Salesforce hasn’t hit its Change Data Capture limit. Salesforce subscriptions use Change Data Capture, and Salesforce limits how many objects an org can select for it. That limit is shared with the customer’s other tools. If it’s reached, ask the customer to free up objects, or use a scheduled read action instead.
• The object doesn’t have too many fields selected. Subscriptions fetch the read action’s fields for each changed record, so the same too-many-fields limit applies: a Salesforce object with hundreds of selected fields can fail with a 414 or 431 error.
• The subscription was created. Look for its operation in the Ampersand dashboard, or set up subscribe notifications to hear when a subscription fails.

Subscription lifecycle observability

The dashboard shows an operation when Ampersand creates, updates, or deletes a subscription, with logs describing the action. It does not show a separate operation or log for each incoming webhook. Lifecycle operations provide visibility into subscription setup without waiting for the first data event.

For example, setting up a subscription to Salesforce contacts produces a Subscription Created operation. Receiving a webhook because a contact’s email address changed does not create an operation.

Subscription lifecycle changes can also trigger success or error notifications. See Notifications for the supported events and configuration instructions.