Skip to main content

Events Reference

FormKiQ v1.19.2 has two different document-event channels: EventBridge events for application integrations and SNS messages used by document processing. Match the channel and exact event name; an audit activity type is not automatically a published integration event.

This catalog follows the release's DetailTypeResolver, DocumentExternalSystemExport, DocumentEventType, FolderEventType, and EventServiceSns. Download the payload schemas. Optional fields depend on the operation and available document data; consumers must tolerate additional fields.

EventBridge catalog​

Automatic activity export requires a wired document event bus. The generic commercial template supplies it through the nested EventMessages stack; inspect that stack for its DocumentEventsBus output. The public Core root leaves the storage component’s DocumentEventsBus input empty, so do not assume automatic activity publication is enabled there. Core supports the explicit EVENTBRIDGE action; additional automatic-event wiring requires an approved infrastructure configuration. Event source is formkiq.<AppEnvironment>. The standard AWS envelope has version, id, detail-type, source, account, time, region, resources, and detail.

All built-in names below use the document export detail schema.

Exact detail-typeOriginating activity
New Document Create MetadataA new document record is created.
New Document Create ContentA new document content version is created.
Document Create ContentExisting-version content is updated.
Document RestoreA deleted document is restored.
Document Update MetadataDocument fields or document attributes change.
Document Create MetadataDocument attributes are added.
Document Soft DeleteA document is moved to trash.
Document DeleteA document is deleted.
Document Delete MetadataDocument attributes are deleted.
Document Action EventAn explicit EVENTBRIDGE document action exports a document to its configured eventBusName.

Some activities resolve to the same event name. The resolver uses ordered matching rules, and unmatched activity groups are not exported as an Unknown event. Do not infer one event per individual attribute change.

Document export schema​

detail contains a document object. Its stable identifiers are documentId and siteId; available document metadata is included alongside the fields below. For a deletion, the remaining payload can be sparse because the document record is already gone.

Field in detail.documentShape and meaning
documentId, siteIdString document and site identifiers.
artifactIdOptional string artifact identifier.
path, contentType, contentLength, datesAvailable document metadata; do not require these for a deletion.
urlOptional presigned content URL. Treat it as a credential; it can expire before consumption or no longer resolve after deletion.
attributesObject keyed by attribute name, containing typed attribute values. The v1.19.2 exporter reads one page of up to 100 attributes, so fetch authoritative metadata when completeness matters.
changedObject containing old values of changed document fields. It is not a JSON Patch or a complete after-image.
addedAttributesArray of added attribute names, when applicable.
changedAttributesObject keyed by attribute name containing prior typed values for changed/deleted attributes.
status, timestampAvailable antivirus tag values, rather than event delivery status.

Illustrative event, with optional presigned URL omitted:

{
"version": "0",
"id": "example-delivery-id",
"detail-type": "Document Update Metadata",
"source": "formkiq.prod",
"account": "123456789012",
"time": "2026-11-16T12:00:00Z",
"region": "us-east-2",
"resources": [],
"detail": {
"document": {
"documentId": "example-document-id",
"siteId": "finance",
"path": "invoices/invoice-1001.pdf",
"changed": {"path": "incoming/invoice-1001.pdf"},
"attributes": {"Status": {"stringValue": "Approved"}}
}
}
}

Example rule pattern:

{
"source": ["formkiq.prod"],
"detail-type": ["Document Update Metadata"],
"detail": {"document": {"siteId": ["finance"]}}
}

See Integrate Custom Code with EventBridge for target setup.

SNS processing catalog​

The message body is JSON. SNS-to-Lambda delivery wraps it in Records[].Sns.Message as a string; parse that string before reading the FormKiQ fields. An SQS subscription may add an SNS envelope unless raw-message delivery is enabled.

Exact body typePayload schemaPurpose
createDocument processingProcess newly created content.
updateDocument processingProcess updated content.
deleteDocument processingProcess document deletion.
softDeleteDocument processingProcess soft deletion.
actionsDocument processingContinue document actions.
folder_moveFolder moveMove a folder and its contents asynchronously.
testNotificationNotification testDeliver a notification using saved site configuration.

Document processing: string fields type, siteId, documentId, and optional artifactId, s3bucket, s3key, userId, path, contentType, content, url; tags is a string-to-string object. Fields are populated by the producer, not guaranteed for every type. The publisher can omit inline content to keep the message within its size budget. Fetch content through the API or approved storage access when needed.

Folder move: type: "folder_move" and string fields siteId, documentId, sourcePath, destinationPath.

Notification test: type: "testNotification" and string fields siteId, to, userId.

SNS message attributes include type and siteId, and userId where supplied. The publisher strips characters outside letters, digits, slash, and hyphen from site/user message attributes. Use the JSON body as the authoritative identifier; punctuation in a site name may differ from the filter attribute.

Delivery and recovery​

Design consumers to tolerate duplicate deliveries, retries, out-of-order updates, and a document that changes or is deleted before processing. Deduplicate using delivery identity and your own operation key, and make downstream writes idempotent. Re-read authoritative state before applying a sensitive change; the event is a notification, not a transaction boundary.

Do not send events or presigned URLs to untrusted buses, logs, or recipients. Restrict event-bus rules, SNS subscriptions, target roles, and queues to the intended sites and services. Retry transient failures with backoff and route exhausted failures to a monitored dead-letter queue. Reconcile periodically so a missed integration event does not permanently desynchronize systems.

Module callbacks, such as incoming DocuSign notifications, have their own provider contracts. They are not additional built-in EventBridge detail-type values in this catalog. See the module's documentation and configured webhook contract.