> ## Documentation Index > Fetch the complete documentation index at: https://docs.maadify.com/llms.txt > Use this file to discover all available pages before exploring further. # Triggers > Start parent agent runs with schedules or webhooks ## What a trigger does A trigger starts a parent agent run automatically. Every trigger is attached to a **parent agent tenant relationship** (sender to receiver), so the run executes inside the relationship that owns the configured tools and permissions. Each trigger has: * A **tenant relationship** that defines which sender drives the workflow and which receiver runs it. * A **trigger tool** (a schedule or a connector webhook event). * A **prompt template** that Maadify renders with the trigger payload and sends to the parent agent. * An **active** toggle that controls whether incoming events are processed. Configured Triggers grid showing trigger cards with sender, receiver, connector, and active status ## Trigger types Maadify supports two trigger sources: * **Schedule**: a cron-based job that fires the parent agent on a recurring interval. Schedules are managed by Maadify directly and do not require an external connector. * **Webhook/Trigger Tool**: a connector event delivered through the configured app (for example, a new email, a new row, or a new form submission). Maadify deploys the listener to the connector. Schedule trigger configuration showing the cron builder and frequency options Webhook trigger configuration showing connector property fields and the deployed webhook URL ## Add a trigger From the parent agent canvas, expand **Configured Triggers** and select **Add Trigger**. You need `parent_agents.update` and `trigger_tools.create` permissions on the owning tenant. Pick the **sender to receiver** relationship that should own the run. Only active relationships for this parent agent appear. Tenant relationship picker showing sender and receiver pairings for the parent agent Select **Schedule** or a connector trigger tool. Toggle **Shared** to browse trigger tools from other tenants you have access to. Trigger tool grid showing schedule and connector trigger tools with the shared filter toggle * For **Schedule**, build the cron expression in the schedule input. * For **Trigger Tool**, fill in the connector property fields. Select an existing prompt template or create a new one. The template renders with the incoming payload before it is sent to the parent agent (see [Prompt template variables](#prompt-template-variables)). Trigger dialog showing the prompt template selector and editor Select **Create Trigger**. Maadify deploys the schedule and/or event listener. You can disable a trigger without deleting it. In the trigger dialog, toggle **Active** off to stop processing incoming events while keeping the configuration in place. ## Edit, disable, or remove a trigger Each trigger card on the canvas exposes the actions you need. * **Edit Details**: opens the same dialog used for creation. Use the **Active** toggle to enable or disable the trigger. Editing requires `trigger_tools.update`. * **Remove Trigger**: deletes the trigger and queues an external cleanup. Removal requires `trigger_tools.delete`. ## How Tool Triggers Run Tool triggers do not call the parent agent directly. They land in a queue so the run can be retried, traced, and rate-limited. The queues messages in order to be processed by Maadify. All active messages will be processed and failed checks are recorded in **Workflow runs** with the reason. The worker exposes the request payload to the prompt template under the trigger's tool key, then renders the template with Jinja. The worker signs in as the tenant integration user and starts a parent agent run with the rendered prompt and the original payload as context variables. You can see the row immediately in **Workflow runs**. Events older than five minutes (relative to the event timestamp) are skipped to prevent re-processing stale messages on retries. Failed messages are retried automatically up to the configured `MAX_RETRIES` (default 3) and then archived. ## Prompt template variables Trigger prompt templates use the same Jinja syntax as tool execution payloads. The trigger payload is exposed under a tool-keyed namespace so you can reference any field in the request body. * **Trigger payload**: `{{ {tool_name}_{tool_id}. }}` — for example `{{ new_email_42.subject }}`. * **Per-trigger payload**: `{{ {tool_name}_{trigger_id}. }}` — useful when you want to disambiguate between multiple triggers using the same tool. * **System variables**: `{{ system.current_datetime }}` is always populated with the run start time. Use the variable picker in the prompt template editor to insert the right path. The picker also exposes runtime inputs and structured outputs that downstream sub-agents can rely on. The same payload is stored in the run's context variables, so rules and tool executions further down the workflow can reference `{tool_name}_{tool_id}` and `{tool_name}_{trigger_id}` paths the same way. ## Monitor triggers in Workflow runs Trigger executions are visible on the **Agent activity** page. Switch the segmented control to **Workflow runs** to see only trigger-driven executions. The table includes: * **Id**: the trigger execution id (used for re-runs). * **Trigger** and **Connector**: which trigger tool fired and which connector delivered it. * **Sender** and **Receiver**: the tenants involved in the relationship. * **Date**, **Status** (pending, success, error), and links to view the **Request** and **Response** payloads. Workflow runs table showing trigger executions with status, request, and response columns Each column header opens a filter popover. Select multiple rows and use **Re-run Selected** to enqueue them again. Re-run skips executions that are still in flight (status pending) and any executions that did not originate from a webhook (for example, schedule-based runs that were dispatched directly). Workflow runs table with multiple rows selected and the Re-run Selected button ## Permissions | Action | Required permission | | ------------------------ | ------------------------------------------------- | | View configured triggers | `trigger_tools` read access on the tenant | | Add a trigger | `trigger_tools.create` and `parent_agents.update` | | Edit or toggle active | `trigger_tools.update` | | Remove a trigger | `trigger_tools.delete` | | Re-run workflow runs | `trigger_executions` access on the tenant | Removing a trigger is irreversible. The cleanup worker deletes the deployed connector listener or cron job, and the trigger row is removed from the database. ## Troubleshooting * Confirm the trigger is **Active** and the parent agent is enabled for the receiving tenant. * Check **Workflow runs** for an entry with the failure reason (inactive trigger, hidden parent agent, missing webhook). * Verify the connector is still authenticated and the deployed listener has not been removed in the connector app. * Open the trigger and confirm the cron expression in the schedule builder. * Check that the parent agent tenant relationship is active. * Inspect **Workflow runs** for failed schedule executions and review the response body for error details. * Confirm the path uses `{tool_name}_{tool_id}` and matches a field in the request payload sample. * Open a recent execution in **Workflow runs** and inspect the **Request** payload to verify the field is present. * Re-run only works for completed executions that originated from a webhook. In-flight (pending) rows and direct schedule runs are skipped automatically. * The toast message lists which ids were skipped and why.