Event Triggers - Pinkfish - AI Agents & Workflows for Getting Work Done

Overview

Resource Event Triggers automatically start workflows when data changes in your Datastores, Filestores, Knowledge Bases, or Vaults. Build reactive systems that respond instantly to creates, updates, and deletes without polling or manual intervention.

Supported Resources

Event triggers work with these resource collections:

Structured Datastores - Collection-level and item-level triggers
Unstructured Datastores - Collection-level triggers only
Filestores - Collection-level and file-level triggers
Knowledge Bases - Collection-level and file-level triggers
Vaults - Collection-level triggers only

Trigger Events

onCreate

Fires when a new item or file is added to a collection. Available at:

✅ Collection level (monitors all creates)
❌ Item/file level (not supported - items don’t exist before creation)

onEdit

Fires when an existing item or file is modified. Available at:

✅ Collection level (monitors all edits)
✅ Item/file level (monitors specific items)

onDelete

Fires when an item or file is removed. Available at:

✅ Collection level (monitors all deletions)
✅ Item/file level (monitors specific items)

Trigger Levels

Collection-Level Triggers

Monitor all items in a collection automatically. Configuration:

Set via collection management UI in the Resources section
Applies to every item/file in the collection

Item/File-Level Triggers

Monitor specific items or files individually. Available for:

🚧 Structured Datastores (individual rows) - Coming soon
✅ Filestores (individual files)
✅ Knowledge Bases (individual files)
❌ Unstructured Datastores (collection-level only)
❌ Vaults (collection-level only)

Configuration:

Set via UI when viewing/editing items or files
Set via triggerUrls parameter when creating or updating items/files via API
Only fires for that particular item/file

Trigger Structure

Triggers use a consistent format across all resource types:

{
  "triggerUrls": [
    {
      "event": "onCreate",
      "url": "https://triggers.app.pinkfish.ai/ext/triggers/abc123",
      "apiKey": "your-api-key",
      "triggerLevel": "collection"
    },
    {
      "event": "onEdit",
      "url": "https://triggers.app.pinkfish.ai/ext/triggers/def456",
      "apiKey": "your-api-key-2",
      "triggerLevel": "item"
    },
    {
      "event": "onDelete",
      "url": "https://triggers.app.pinkfish.ai/ext/triggers/ghi789",
      "apiKey": "your-api-key-3",
      "triggerLevel": "item"
    }
  ]
}

Fields:

event (required) - onCreate, onEdit, or onDelete
url (required) - Webhook endpoint to call (typically a Pinkfish workflow API trigger)
apiKey (required) - API key for authenticating with the endpoint
triggerLevel (optional) - “collection” or “item” (auto-detected if not specified)

Trigger Payloads

Datastore Triggers (Structured & Unstructured)

onCreate/onDelete events:

{
  "event": "onCreate",
  "itemId": "abc123def456",
  "providerId": "user-provider-id",
  "collectionId": "collection-id",
  "collectionType": "datastore",
  "key": "user-settings",
  "sortField": "theme-preferences",
  "content": {
    "theme": "dark",
    "notifications": true
  },
  "metadata": {
    "version": "1.0"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "triggerLevel": "item"
}

onEdit events (includes changed data):

{
  "event": "onEdit",
  "itemId": "abc123def456",
  "providerId": "user-provider-id",
  "collectionId": "collection-id",
  "collectionType": "datastore",
  "key": "user-settings",
  "sortField": "theme-preferences",
  "content": {
    "theme": "light",
    "notifications": true
  },
  "metadata": {
    "version": "1.1"
  },
  "changed": {
    "content": {
      "theme": "dark"
    },
    "metadata": {
      "version": "1.0"
    }
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T15:45:00.000Z",
  "triggerLevel": "item"
}

Filestorage Triggers

onCreate/onEdit/onDelete events:

{
  "event": "onCreate",
  "itemId": "file-abc123",
  "providerId": "user-provider-id",
  "collectionId": "collection-id",
  "collectionType": "filestorage",
  "filename": "config.json",
  "filepath": "file-storage/collection-id/config.json",
  "fileSize": 1024,
  "mimeType": "application/json",
  "signedUrl": "https://storage.googleapis.com/...",
  "metadata": {
    "version": "1.0",
    "environment": "production"
  },
  "isPublic": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "triggerLevel": "file"
}

Note: The signedUrl provides access to file content and is valid for 7 days.

Vault Triggers

Same structure as datastore triggers, with collectionType: "vault" and isSecret: true. Note: Vault triggers are collection-level only - individual secret items cannot have triggers.

Setting Up Triggers

Collection-Level (via UI)

Navigate to Resources → [Your Collection]
Click “Settings” or “Edit Collection”
Add trigger URLs in the “Event Triggers” section
Select events (onCreate, onEdit, onDelete)
Provide webhook URL and API key
Save changes

Item/File-Level (via API)

When creating items:

POST /memory/items?collectionId=xxx
{
  "key": "user-settings",
  "content": {"theme": "dark"},
  "triggerUrls": [
    {
      "event": "onEdit",
      "url": "https://triggers.app.pinkfish.ai/ext/triggers/abc123",
      "apiKey": "your-api-key"
    }
  ]
}

When uploading files:

POST /filestorage/items/upload?collectionId=xxx
{
  "file": [file data],
  "triggerUrls": [
    {
      "event": "onEdit",
      "url": "https://triggers.app.pinkfish.ai/ext/triggers/def456",
      "apiKey": "your-api-key"
    }
  ]
}

When updating items (PATCH/PUT):

PATCH /memory/items/{id}?collectionId=xxx
{
  "content": {"theme": "light"},
  "triggerUrls": [
    {
      "event": "onEdit",
      "url": "https://triggers.app.pinkfish.ai/ext/triggers/abc123",
      "apiKey": "your-api-key"
    }
  ]
}

Rate Limiting

onEdit Event Rate Limiting

To prevent infinite loops and excessive executions:

Limit: Maximum 2 trigger executions per minute per item/file
Window: 60-second rolling window
Applies to: onEdit events only
Behavior: Excess triggers are dropped (not queued)

Why rate limiting? Without rate limiting, you could create infinite loops:

Workflow A edits item → triggers Workflow B
Workflow B edits same item → triggers Workflow A
Loop continues indefinitely

Best practice: Set triggerChanges: false in update operations within triggered workflows to prevent recursive triggers.

No Rate Limiting

onCreate and onDelete events have no rate limiting since they can’t create loops.

Testing Triggers

Test your triggers before production deployment:

Test Collection Triggers

POST /datacollection/{collectionId}/triggers/test
{
  "event": "onEdit",
  "testData": {
    "key": "test-item",
    "content": {"test": true}
  }
}

Test Item Triggers

POST /memory/test-trigger?collectionId=xxx
{
  "url": "https://triggers.app.pinkfish.ai/ext/triggers/abc123",
  "apiKey": "your-api-key",
  "dataStoreId": "item-id",
  "data": {
    "key": "test-item",
    "content": {"test": true}
  }
}

Response:

{
  "message": "Triggered successfully",
  "log": {
    "runId": "trigger-run-123",
    "status": "success",
    "executionTime": 1523,
    "event": "onTest"
  }
}

Note: To monitor triggered workflow executions, use the Orchestration Monitor.

API Reference

Create Item with Triggers

POST /memory/items?collectionId=xxx

{
  "key": "item-key",
  "content": {...},
  "triggerUrls": [...]
}

Create File with Triggers

POST /filestorage/items/upload?collectionId=xxx

Multipart form data with triggerUrls field.

Update Triggers on Existing Item

PUT /memory/items/{id}?collectionId=xxx

{
  "content": {...},
  "triggerUrls": [...]
}

Set Collection-Level Triggers

PATCH /datacollection/{collectionId}

{
  "triggerUrls": [...]
}

Test Triggers

Collection-level:

POST /datacollection/{collectionId}/triggers/test

Item-level:

POST /memory/test-trigger?collectionId=xxx

Limitations

onCreate Restrictions

Cannot be set at item/file level (only collection level)
Items must exist before triggers can be attached to them
Use collection-level onCreate for new item monitoring

Rate Limiting

onEdit events: 2 executions per minute per item/file
onCreate/onDelete: No rate limits

Execution

Triggers execute asynchronously (non-blocking)
Failed triggers don’t retry automatically (implement retry in your workflow)
Trigger logs retained for debugging and monitoring

Structured Datastore
Unstructured Datastore
Filestorage
Vault
Knowledge Base
Workflow Triggers - Overview of all trigger types

Get Started

Organization

Agents

Workflows

Resources

Integrations

Orchestration

Credits & Pricing

Skills

How To Guides

Release Notes

Support

​Overview

​Supported Resources

​Trigger Events

​onCreate

​onEdit

​onDelete

​Trigger Levels

​Collection-Level Triggers

​Item/File-Level Triggers

​Trigger Structure

​Trigger Payloads

​Datastore Triggers (Structured & Unstructured)

​Filestorage Triggers

​Vault Triggers

​Setting Up Triggers

​Collection-Level (via UI)

​Item/File-Level (via API)

​Rate Limiting

​onEdit Event Rate Limiting

​No Rate Limiting

​Testing Triggers

​Test Collection Triggers

​Test Item Triggers

​API Reference

​Create Item with Triggers

​Create File with Triggers

​Update Triggers on Existing Item

​Set Collection-Level Triggers

​Test Triggers

​Limitations

​onCreate Restrictions

​Rate Limiting

​Execution

​Related Documentation

Overview

Supported Resources

Trigger Events

onCreate

onEdit

onDelete

Trigger Levels

Collection-Level Triggers

Item/File-Level Triggers

Trigger Structure

Trigger Payloads

Datastore Triggers (Structured & Unstructured)

Filestorage Triggers

Vault Triggers

Setting Up Triggers

Collection-Level (via UI)

Item/File-Level (via API)

Rate Limiting

onEdit Event Rate Limiting

No Rate Limiting

Testing Triggers

Test Collection Triggers

Test Item Triggers

API Reference

Create Item with Triggers

Create File with Triggers

Update Triggers on Existing Item

Set Collection-Level Triggers

Test Triggers

Limitations

onCreate Restrictions

Rate Limiting

Execution

Related Documentation