Triggers API: Create and Manage Automations

Automate Forjinn chatflow executions with cron-based schedules or incoming webhooks from Telegram, Slack, and other platforms, and retrieve execution results.

Triggers let you run chatflow executions automatically — either on a schedule (cron) or in response to an incoming HTTP request (webhook). A trigger is always associated with a specific chatflow and node within that flow. When a trigger fires, Forjinn runs the chatflow with the configured payload and records the result.

Trigger types

Type	Description
`cron`	Executes on a schedule defined by a cron expression
`webhook`	Executes when a POST request arrives at the trigger's webhook URL

Webhook triggers support several platform integrations (e.g., Telegram) that handle signature verification automatically when you provide a webhookSecret or webhookBotToken.

The trigger object

idstring

UUID of the trigger.

namestring

Display name.

chatflowIdstring

The chatflow this trigger executes.

nodeIdstring

The specific node within the chatflow that receives the trigger payload.

typestring

"cron" or "webhook".

cronExpressionstring

Cron expression (e.g., "30 9 * * *" for daily at 09:30). Present on cron triggers only.

enabledboolean

Whether the trigger is active.

webhookPlatformstring

For webhook triggers, the source platform (e.g., "telegram").

webhookSecretstring

Secret used to verify incoming webhook signatures.

triggerMessagestring

Message text sent to the chatflow when the trigger fires (for cron triggers).

executionCountinteger

Total number of times this trigger has fired.

maxExecutionsinteger

Optional cap on total executions. Once reached, the trigger stops firing.

timeoutinteger

Execution timeout in seconds (default: 300).

lastExecutedstring

ISO 8601 timestamp of the most recent execution.

nextExecutionstring

ISO 8601 timestamp of the next scheduled execution (cron triggers only).

notificationEmailstring

Optional email address to notify on execution failure.

createdDatestring

ISO 8601 creation timestamp.

updatedDatestring

ISO 8601 last-updated timestamp.

Create a trigger

POST /api/v1/triggers

namestringRequired

Display name for the trigger.

chatflowIdstringRequired

UUID of the chatflow to execute.

nodeIdstringRequired

ID of the node within the chatflow that handles trigger input.

typestringRequired

"cron" or "webhook".

cronExpressionstring

Required when type is "cron". Standard 5-field cron expression (minute hour day month weekday).

triggerMessagestring

Message sent to the chatflow on each cron execution.

enabledboolean

Whether to activate the trigger immediately (default: true).

webhookPlatformstring

Platform for webhook triggers. Use "telegram" to enable Telegram-specific handling.

webhookSecretstring

Shared secret for verifying webhook payloads.

webhookBotTokenstring

Telegram bot token. When provided alongside webhookPlatform: "telegram", Forjinn registers the webhook with Telegram automatically.

maxExecutionsinteger

Maximum number of times this trigger will fire before disabling itself.

timeoutinteger

Execution timeout in seconds (default: 300).

notificationEmailstring

Email address to notify on execution failure.

Example — cron trigger

curl -X POST https://your-forjinn-instance.com/api/v1/triggers \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Morning Briefing",
    "chatflowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "nodeId": "trigger-node-001",
    "type": "cron",
    "cronExpression": "0 8 * * *",
    "triggerMessage": "Generate today'\''s news summary for the sales team.",
    "enabled": true,
    "notificationEmail": "ops@example.com"
  }'

const response = await fetch('https://your-forjinn-instance.com/api/v1/triggers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Daily Morning Briefing',
    chatflowId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    nodeId: 'trigger-node-001',
    type: 'cron',
    cronExpression: '0 8 * * *',
    triggerMessage: "Generate today's news summary for the sales team.",
    enabled: true,
    notificationEmail: 'ops@example.com',
  }),
});

const trigger = await response.json();

Response — 201 Created

{
  "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
  "name": "Daily Morning Briefing",
  "chatflowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "nodeId": "trigger-node-001",
  "type": "cron",
  "cronExpression": "0 8 * * *",
  "triggerMessage": "Generate today's news summary for the sales team.",
  "enabled": true,
  "executionCount": 0,
  "timeout": 300,
  "notificationEmail": "ops@example.com",
  "nextExecution": "2024-05-02T08:00:00.000Z",
  "createdDate": "2024-05-01T10:00:00.000Z",
  "updatedDate": "2024-05-01T10:00:00.000Z"
}

Example — webhook trigger

curl -X POST https://your-forjinn-instance.com/api/v1/triggers \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub PR Webhook",
    "chatflowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "nodeId": "webhook-node-002",
    "type": "webhook",
    "webhookSecret": "my-github-secret",
    "enabled": true
  }'

const response = await fetch('https://your-forjinn-instance.com/api/v1/triggers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'GitHub PR Webhook',
    chatflowId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    nodeId: 'webhook-node-002',
    type: 'webhook',
    webhookSecret: 'my-github-secret',
    enabled: true,
  }),
});

Once created, the webhook URL for this trigger is:

POST /api/v1/triggers/webhook/<nodeId>

List triggers

GET /api/v1/triggers

Returns all triggers in your active workspace.

includeResultsboolean

If true, each trigger in the response includes a recentResults array with its last few execution outputs.

curl "https://your-forjinn-instance.com/api/v1/triggers?includeResults=true" \
  -H "Authorization: Bearer fj-abc123def456"

const response = await fetch('https://your-forjinn-instance.com/api/v1/triggers?includeResults=true', {
  headers: { 'Authorization': 'Bearer fj-abc123def456' },
});

const triggers = await response.json();

Get a trigger

GET /api/v1/triggers/:id

idstringRequired

UUID of the trigger.

curl https://your-forjinn-instance.com/api/v1/triggers/d4e5f6a7-b8c9-0123-def0-123456789012 \
  -H "Authorization: Bearer fj-abc123def456"

const id = 'd4e5f6a7-b8c9-0123-def0-123456789012';
const response = await fetch(`https://your-forjinn-instance.com/api/v1/triggers/${id}`, {
  headers: { 'Authorization': 'Bearer fj-abc123def456' },
});

const trigger = await response.json();

Get trigger execution results

GET /api/v1/triggers/:id/results

Returns the most recent execution records for a trigger — what message was sent and what the chatflow responded.

idstringRequired

UUID of the trigger.

limitinteger

Maximum number of results to return (default: 10).

curl "https://your-forjinn-instance.com/api/v1/triggers/d4e5f6a7-b8c9-0123-def0-123456789012/results?limit=5" \
  -H "Authorization: Bearer fj-abc123def456"

const id = 'd4e5f6a7-b8c9-0123-def0-123456789012';
const response = await fetch(`https://your-forjinn-instance.com/api/v1/triggers/${id}/results?limit=5`, {
  headers: { 'Authorization': 'Bearer fj-abc123def456' },
});

const results = await response.json();

Response — 200 OK

[
  {
    "executedAt": "2024-05-02T08:00:03.000Z",
    "input": "Generate today's news summary for the sales team.",
    "output": "Here is today's briefing: Markets opened higher following...",
    "sourceDocuments": null,
    "usedTools": null,
    "chatId": "trigger-d4e5f6a7-1714636800000"
  }
]

Update a trigger

PUT /api/v1/triggers/:id

idstringRequired

UUID of the trigger to update.

Send only the fields you want to change. Updating a trigger briefly deactivates it, applies the changes, and reactivates it if enabled is true.

namestring

Updated display name.

cronExpressionstring

Updated cron expression.

triggerMessagestring

Updated message sent on each execution.

enabledboolean

Enable or disable the trigger.

maxExecutionsinteger

Updated execution cap.

curl -X PUT https://your-forjinn-instance.com/api/v1/triggers/d4e5f6a7-b8c9-0123-def0-123456789012 \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "cronExpression": "0 9 * * 1-5",
    "triggerMessage": "Generate today'\''s briefing (weekdays only)."
  }'

const id = 'd4e5f6a7-b8c9-0123-def0-123456789012';
const response = await fetch(`https://your-forjinn-instance.com/api/v1/triggers/${id}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    cronExpression: '0 9 * * 1-5',
    triggerMessage: "Generate today's briefing (weekdays only).",
  }),
});

const updated = await response.json();

Delete a trigger

DELETE /api/v1/triggers/:id

idstringRequired

UUID of the trigger to delete.

Deletes the trigger and immediately stops any scheduled or webhook-based execution. Returns 204 No Content on success.

curl -X DELETE https://your-forjinn-instance.com/api/v1/triggers/d4e5f6a7-b8c9-0123-def0-123456789012 \
  -H "Authorization: Bearer fj-abc123def456"

const id = 'd4e5f6a7-b8c9-0123-def0-123456789012';
await fetch(`https://your-forjinn-instance.com/api/v1/triggers/${id}`, {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer fj-abc123def456' },
});
// 204 No Content on success

Incoming webhook endpoint

This is the public endpoint that external services POST to in order to fire a webhook trigger. No API key is required — authentication is handled via the webhookSecret you configured on the trigger.

POST /api/v1/triggers/webhook/:nodeId

nodeIdstringRequired

The nodeId of the trigger (matches the nodeId field on the trigger object).

Send any JSON payload. Forjinn passes the raw body and headers to the chatflow for processing.

# Example: simulating a GitHub push event
curl -X POST https://your-forjinn-instance.com/api/v1/triggers/webhook/webhook-node-002 \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=abc123..." \
  -d '{
    "action": "opened",
    "pull_request": {
      "title": "Add new feature",
      "body": "This PR adds X and Y.",
      "user": { "login": "dev-user" }
    }
  }'

const response = await fetch('https://your-forjinn-instance.com/api/v1/triggers/webhook/webhook-node-002', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'opened',
    pull_request: {
      title: 'Add new feature',
      body: 'This PR adds X and Y.',
      user: { login: 'dev-user' },
    },
  }),
});

const result = await response.json();

The response is the chatflow's output for this execution, returned synchronously.

Triggers API: Create and Manage Automations

On this page