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-type | Originating activity |
|---|---|
New Document Create Metadata | A new document record is created. |
New Document Create Content | A new document content version is created. |
Document Create Content | Existing-version content is updated. |
Document Restore | A deleted document is restored. |
Document Update Metadata | Document fields or document attributes change. |
Document Create Metadata | Document attributes are added. |
Document Soft Delete | A document is moved to trash. |
Document Delete | A document is deleted. |
Document Delete Metadata | Document attributes are deleted. |
Document Action Event | An 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.document | Shape and meaning |
|---|---|
documentId, siteId | String document and site identifiers. |
artifactId | Optional string artifact identifier. |
path, contentType, contentLength, dates | Available document metadata; do not require these for a deletion. |
url | Optional presigned content URL. Treat it as a credential; it can expire before consumption or no longer resolve after deletion. |
attributes | Object 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. |
changed | Object containing old values of changed document fields. It is not a JSON Patch or a complete after-image. |
addedAttributes | Array of added attribute names, when applicable. |
changedAttributes | Object keyed by attribute name containing prior typed values for changed/deleted attributes. |
status, timestamp | Available 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 type | Payload schema | Purpose |
|---|---|---|
create | Document processing | Process newly created content. |
update | Document processing | Process updated content. |
delete | Document processing | Process document deletion. |
softDelete | Document processing | Process soft deletion. |
actions | Document processing | Continue document actions. |
folder_move | Folder move | Move a folder and its contents asynchronously. |
testNotification | Notification test | Deliver 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.