From 6323e939e4284504e9b863b9341f06e0d635b764 Mon Sep 17 00:00:00 2001 From: Jaehyun Lim Date: Tue, 8 Sep 2026 14:36:47 -0700 Subject: [PATCH 1/2] notifications: add read.backfill.error event type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Backfill read failures previously had no builder-facing event — the server published read.triggered.error for every read failure. The server now emits read.backfill.error when a backfill read fails (amp-labs/server#7312); this adds the event type to the NotificationEventType enum and defines its payload schema. Co-Authored-By: Claude Fable 5 --- api/api.yaml | 1 + api/generated/api.bundled.json | 1 + api/generated/api.json | 6 + notifications/generated/notifications.json | 203 +++++++++++++++++++++ notifications/notifications.yaml | 34 ++++ 5 files changed, 245 insertions(+) diff --git a/api/api.yaml b/api/api.yaml index bea2592..d15d0c7 100644 --- a/api/api.yaml +++ b/api/api.yaml @@ -7255,6 +7255,7 @@ components: - "installation.deleted" - "read.schedule.paused" - "read.backfill.done" + - "read.backfill.error" - "read.triggered.done" - "read.triggered.error" - "write.async.done" diff --git a/api/generated/api.bundled.json b/api/generated/api.bundled.json index 491c58f..08c8528 100644 --- a/api/generated/api.bundled.json +++ b/api/generated/api.bundled.json @@ -10332,6 +10332,7 @@ "installation.deleted", "read.schedule.paused", "read.backfill.done", + "read.backfill.error", "read.triggered.done", "read.triggered.error", "write.async.done", diff --git a/api/generated/api.json b/api/generated/api.json index 9f0677d..94620db 100644 --- a/api/generated/api.json +++ b/api/generated/api.json @@ -61929,6 +61929,7 @@ "installation.deleted", "read.schedule.paused", "read.backfill.done", + "read.backfill.error", "read.triggered.done", "read.triggered.error", "write.async.done", @@ -61993,6 +61994,7 @@ "installation.deleted", "read.schedule.paused", "read.backfill.done", + "read.backfill.error", "read.triggered.done", "read.triggered.error", "write.async.done", @@ -62669,6 +62671,7 @@ "installation.deleted", "read.schedule.paused", "read.backfill.done", + "read.backfill.error", "read.triggered.done", "read.triggered.error", "write.async.done", @@ -62719,6 +62722,7 @@ "installation.deleted", "read.schedule.paused", "read.backfill.done", + "read.backfill.error", "read.triggered.done", "read.triggered.error", "write.async.done", @@ -78323,6 +78327,7 @@ "installation.deleted", "read.schedule.paused", "read.backfill.done", + "read.backfill.error", "read.triggered.done", "read.triggered.error", "write.async.done", @@ -78369,6 +78374,7 @@ "installation.deleted", "read.schedule.paused", "read.backfill.done", + "read.backfill.error", "read.triggered.done", "read.triggered.error", "write.async.done", diff --git a/notifications/generated/notifications.json b/notifications/generated/notifications.json index 47c4037..659a8fc 100644 --- a/notifications/generated/notifications.json +++ b/notifications/generated/notifications.json @@ -496,6 +496,99 @@ } ] }, + "ReadBackfillErrorData": { + "title": "Read Backfill Error Data", + "description": "Data payload for read.backfill.error notifications.", + "allOf": [ + { + "title": "Installation Fields", + "type": "object", + "description": "Common fields present in installation-related notifications.", + "required": [ + "projectId", + "provider", + "integrationId", + "integrationName", + "installationId", + "groupRef", + "groupName", + "connectionId", + "consumerRef", + "consumerName" + ], + "properties": { + "projectId": { + "type": "string", + "description": "The Ampersand Project ID.", + "example": "550e8400-e29b-41d4-a716-446655440000" + }, + "provider": { + "type": "string", + "description": "The SaaS API that we are integrating with.", + "example": "salesforce" + }, + "integrationId": { + "type": "string", + "description": "The ID of the integration.", + "example": "550e8400-e29b-41d4-a716-446655440000" + }, + "integrationName": { + "type": "string", + "description": "The name of the integration.", + "example": "Salesforce Integration" + }, + "installationId": { + "type": "string", + "description": "The ID of the Ampersand installation.", + "example": "550e8400-e29b-41d4-a716-446655440000" + }, + "connectionId": { + "type": "string", + "description": "The ID of the connection.", + "example": "550e8400-e29b-41d4-a716-446655440000" + }, + "groupRef": { + "type": "string", + "description": "The ID that your app uses to identify the group of users.", + "example": "customer-group-ref" + }, + "groupName": { + "type": "string", + "description": "The display name of the group of users.", + "example": "Customer Name" + }, + "consumerRef": { + "type": "string", + "description": "The reference ID of the consumer that triggered the notification.", + "example": "user-123" + }, + "consumerName": { + "type": "string", + "description": "The name of the consumer that triggered the notification.", + "example": "John Doe" + } + } + }, + { + "type": "object", + "required": [ + "objectName" + ], + "properties": { + "objectName": { + "type": "string", + "description": "The name of the object for which the backfill failed.", + "example": "Account" + }, + "error": { + "type": "string", + "description": "The error that occurred during the backfill.", + "example": "Authentication failed" + } + } + } + ] + }, "ReadSchedulePausedData": { "title": "Read Schedule Paused Data", "description": "Data payload for read.schedule.paused notifications.", @@ -2039,6 +2132,116 @@ } } }, + "ReadBackfillErrorNotificationPayload": { + "title": "Read Backfill Error Notification Payload", + "description": "Payload structure for read.backfill.error notifications sent to webhook destinations.\nFor Kinesis destinations, only the `data` object is sent.\n", + "type": "object", + "required": [ + "notificationType", + "data" + ], + "properties": { + "notificationType": { + "type": "string", + "enum": [ + "read.backfill.error" + ] + }, + "data": { + "title": "Read Backfill Error Data", + "description": "Data payload for read.backfill.error notifications.", + "allOf": [ + { + "title": "Installation Fields", + "type": "object", + "description": "Common fields present in installation-related notifications.", + "required": [ + "projectId", + "provider", + "integrationId", + "integrationName", + "installationId", + "groupRef", + "groupName", + "connectionId", + "consumerRef", + "consumerName" + ], + "properties": { + "projectId": { + "type": "string", + "description": "The Ampersand Project ID.", + "example": "550e8400-e29b-41d4-a716-446655440000" + }, + "provider": { + "type": "string", + "description": "The SaaS API that we are integrating with.", + "example": "salesforce" + }, + "integrationId": { + "type": "string", + "description": "The ID of the integration.", + "example": "550e8400-e29b-41d4-a716-446655440000" + }, + "integrationName": { + "type": "string", + "description": "The name of the integration.", + "example": "Salesforce Integration" + }, + "installationId": { + "type": "string", + "description": "The ID of the Ampersand installation.", + "example": "550e8400-e29b-41d4-a716-446655440000" + }, + "connectionId": { + "type": "string", + "description": "The ID of the connection.", + "example": "550e8400-e29b-41d4-a716-446655440000" + }, + "groupRef": { + "type": "string", + "description": "The ID that your app uses to identify the group of users.", + "example": "customer-group-ref" + }, + "groupName": { + "type": "string", + "description": "The display name of the group of users.", + "example": "Customer Name" + }, + "consumerRef": { + "type": "string", + "description": "The reference ID of the consumer that triggered the notification.", + "example": "user-123" + }, + "consumerName": { + "type": "string", + "description": "The name of the consumer that triggered the notification.", + "example": "John Doe" + } + } + }, + { + "type": "object", + "required": [ + "objectName" + ], + "properties": { + "objectName": { + "type": "string", + "description": "The name of the object for which the backfill failed.", + "example": "Account" + }, + "error": { + "type": "string", + "description": "The error that occurred during the backfill.", + "example": "Authentication failed" + } + } + } + ] + } + } + }, "ReadSchedulePausedNotificationPayload": { "title": "Read Schedule Paused Notification Payload", "description": "Payload structure for read.schedule.paused notifications sent to webhook destinations.\nFor Kinesis destinations, only the `data` object is sent.\n", diff --git a/notifications/notifications.yaml b/notifications/notifications.yaml index 7e91524..15a896e 100644 --- a/notifications/notifications.yaml +++ b/notifications/notifications.yaml @@ -164,6 +164,24 @@ components: type: string description: The name of the object for which the backfill completed. example: Account + # Read backfill failed event data + ReadBackfillErrorData: + title: Read Backfill Error Data + description: Data payload for read.backfill.error notifications. + allOf: + - $ref: '#/components/schemas/InstallationFields' + - type: object + required: + - objectName + properties: + objectName: + type: string + description: The name of the object for which the backfill failed. + example: Account + error: + type: string + description: The error that occurred during the backfill. + example: "Authentication failed" # Read schedule paused event data ReadSchedulePausedData: title: Read Schedule Paused Data @@ -500,6 +518,22 @@ components: data: $ref: '#/components/schemas/ReadBackfillDoneData' + ReadBackfillErrorNotificationPayload: + title: Read Backfill Error Notification Payload + description: | + Payload structure for read.backfill.error notifications sent to webhook destinations. + For Kinesis destinations, only the `data` object is sent. + type: object + required: + - notificationType + - data + properties: + notificationType: + type: string + enum: [read.backfill.error] + data: + $ref: '#/components/schemas/ReadBackfillErrorData' + ReadSchedulePausedNotificationPayload: title: Read Schedule Paused Notification Payload description: | From d318ce050a660f62b6a56b9f65364ae985cf299a Mon Sep 17 00:00:00 2001 From: jlimatampersand <135054647+jlimatampersand@users.noreply.github.com> Date: Wed, 9 Sep 2026 17:58:30 -0700 Subject: [PATCH 2/2] Apply suggestion from @graphite-app[bot] Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> --- notifications/notifications.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/notifications/notifications.yaml b/notifications/notifications.yaml index 15a896e..d9532aa 100644 --- a/notifications/notifications.yaml +++ b/notifications/notifications.yaml @@ -171,8 +171,10 @@ components: allOf: - $ref: '#/components/schemas/InstallationFields' - type: object + required: - objectName + - error properties: objectName: type: string @@ -182,6 +184,7 @@ components: type: string description: The error that occurred during the backfill. example: "Authentication failed" + # Read schedule paused event data ReadSchedulePausedData: title: Read Schedule Paused Data