> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification payloads

The payload structure depends on your destination type:

* **Webhook destinations**: Payloads include `notificationType` and `data` fields.
* **Kinesis destinations**: Payloads contain the `data` object. The `notificationType` is included in the event metadata.

You can find the OpenAPI spec for notification payloads [on GitHub](https://github.com/amp-labs/openapi/blob/main/notifications/notifications.yaml), or refer to the examples below:

<Note>
  Some payloads may include a `config` field nested within the `data` field. This config contains the complete installation configuration, including read, write, subscribe, and proxy settings.
  The installation.updated event also includes an additional lastConfig field representing the previous configuration.
  If the configuration object is too large to include inline, we will generate a signed URL you can use to fetch full configuration via GET request as a JSON file.

  <Accordion title="Example payload">
    ```json theme={null}
    {
      "notificationType": "installation.updated",
      "data": {
        ...,
        "config": { //If the config content is too large, the config field will be empty and you can retrieve the content from the URL provided in `configURL`.
          "read": {
            "objects": {
              "account": {
                "objectName": "account",
                "destination": "my-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        },
        // "configURL": "https://example.com/config.json" // If the config content is too large to deliver directly, we will provide a signed URL where you can download the content as a JSON file.
        "lastConfig": { // Only for `installation.updated` notifications. If the config is too large, it will be omitted and the content will be available in `lastConfigURL`.
          "read": {
            "objects": {
              "account": {
                "objectName": "account",
                "destination": "my-old-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        }
        // "lastConfigURL": "https://example.com/lastconfig.json"
      }
    }
    ```
  </Accordion>
</Note>

<AccordionGroup>
  <Accordion title="Installation events (created, updated, deleted)">
    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "installation.created",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "config": { //If the config content is too large, the config field will be empty and you can retrieve the content from the URL provided in `configURL`.
          "read": {
            "objects": {
              "account": {
                "objectName": "account",
                "destination": "my-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        },
        "lastConfig": { // Only for `installation.updated` notifications. If the config is too large, it will be omitted and the content will be available in `lastConfigURL`.
          "read": {
            "objects": {
              "account": {
                "objectName": "account",
                "destination": "my-old-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        }
        // "lastConfigURL": "https://example.com/lastconfig.json"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "config": {
        "read": {
          "objects": {
            "Account": {
              "objectName": "Account",
              "destination": "my-webhook",
              "requiredFields": [...],
              "optionalFields": [...]
            }
          }
        }
      }
    }
    ```

    Note: `config` contains the complete installation configuration object including read, write, subscribe, and proxy settings. `installation.updated` includes an additional `lastConfig` field with the previous configuration.
  </Accordion>

  <Accordion title="read.backfill.done">
    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "read.backfill.done",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account"
    }
    ```
  </Accordion>

  <Accordion title="read.schedule.paused">
    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "read.schedule.paused",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "config": {
          "read": {
            "objects": {
              "Account": {
                "objectName": "Account",
                "destination": "my-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        },
        "error": "Authentication failed"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "config": {
        "read": {
          "objects": {
            "Account": {
              "objectName": "Account",
              "destination": "my-webhook",
              "requiredFields": [...],
              "optionalFields": [...]
            }
          }
        }
      },
      "error": "Authentication failed"
    }
    ```

    Note: `config` contains the complete installation configuration object including read, write, subscribe, and proxy settings.
  </Accordion>

  <Accordion title="read.triggered.done">
    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "read.triggered.done",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account",
        "fromTimestamp": "2026-01-01T00:00:00Z",
        "untilTimestamp": "2026-01-01T23:59:59Z"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account",
      "fromTimestamp": "2026-01-01T00:00:00Z",
      "untilTimestamp": "2026-01-01T23:59:59Z"
    }
    ```

    Note: `fromTimestamp` and `untilTimestamp` indicate the time range of the triggered read.
  </Accordion>

  <Accordion title="read.triggered.error">
    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "read.triggered.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account",
        "fromTimestamp": "2026-01-01T00:00:00Z",
        "untilTimestamp": "2026-01-01T23:59:59Z",
        "error": "Authentication failed"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account",
      "fromTimestamp": "2026-01-01T00:00:00Z",
      "untilTimestamp": "2026-01-01T23:59:59Z",
      "error": "Authentication failed"
    }
    ```

    Note: `error` describes what went wrong during the triggered read.
  </Accordion>

  <Accordion title="write.async.done">
    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "write.async.done",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account",
        "success": true,
        "successfulRecordIds": ["provider-record-id-1", "provider-record-id-2"],
        "errors": []
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account",
      "success": true,
      "successfulRecordIds": ["provider-record-id-1", "provider-record-id-2"],
      "errors": []
    }
    ```

    Note: For partial failures, `success` is `false` with both `successfulRecordIds` and `errors` populated.
  </Accordion>

  <Accordion title="Connection events (created, refreshed, deleted)">
    `connection.created`, `connection.refreshed`, and `connection.deleted` share the same payload shape. `notificationType` reflects the specific event.

    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "connection.created",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "provider": "salesforce",
        "groupRef": "customer-group-ref",
        "consumerRef": "user-123",
        "consumerName": "John Doe"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "provider": "salesforce",
      "groupRef": "customer-group-ref",
      "consumerRef": "user-123",
      "consumerName": "John Doe"
    }
    ```
  </Accordion>

  <Accordion title="connection.error">
    <Note>The `error` field is deprecated and kept for backward compatibility. Use `errors` instead. Both fields contain the same value.</Note>

    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "connection.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "provider": "salesforce",
        "groupRef": "customer-group-ref",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "errors": ["Authentication failed", "Token refresh error"],
        "error": ["Authentication failed", "Token refresh error"]
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "provider": "salesforce",
      "groupRef": "customer-group-ref",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "errors": ["Authentication failed", "Token refresh error"],
      "error": ["Authentication failed", "Token refresh error"]
    }
    ```
  </Accordion>

  <Accordion title="destination.webhook.disabled">
    **Webhook destination payload:**

    ```json theme={null}
    {
      "notificationType": "destination.webhook.disabled",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "destinationId": "2e8f4c1a-9b3d-4e7f-8a2c-0d1e2f3a4b5c",
        "destinationName": "production-alerts",
        "url": "https://your-webhook.com"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={null}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "destinationId": "2e8f4c1a-9b3d-4e7f-8a2c-0d1e2f3a4b5c",
      "destinationName": "production-alerts",
      "url": "https://your-webhook.com"
    }
    ```
  </Accordion>
</AccordionGroup>