All docs / Developer Guide

Custom Triggers

Create custom automation recipe triggers that listen for WordPress events.

A trigger defines when a recipe runs. Your custom trigger listens for a WordPress event and fires the recipe system.

Complete Example

This example creates a trigger that fires when a user submits a Contact Form 7 form:

<?php
// File: triggers/cf7-submit-trigger.php

if ( ! defined( 'ABSPATH' ) ) exit;

class IW_CF7Submit_Trigger extends IW_Automation_Trigger {

    function trigger_when() {
        add_action('wpcf7_mail_sent', array($this, 'on_form_submitted'), 10, 1);
    }

    function get_title() {
        return 'Contact Form 7 Submission';
    }

    public function get_desc() {
        return 'when a Contact Form 7 form is submitted';
    }

    function get_contact_email() {
        $submission = $this->pass_vars[0];
        $posted_data = $submission->get_posted_data();
        return isset($posted_data['your-email']) ? $posted_data['your-email'] : '';
    }

    function on_form_submitted($contact_form) {
        $submission = WPCF7_Submission::get_instance();
        if (!$submission) return;

        $this->pass_vars = array($submission, $contact_form);
        $this->trigger();
    }

    function get_log_details() {
        $submission = $this->pass_vars[0];
        $data = $submission->get_posted_data();
        return 'Form: ' . ($data['_wpcf7'] ?? 'unknown');
    }

    // Merge Fields
    public $merge_handlers = array(
        'CF7' => array('Contact Form 7 Data', 'merge_handler_cf7')
    );

    function merge_fields() {
        return array('CF7' => array(
            'your-name'    => 'Name',
            'your-email'   => 'Email',
            'your-subject' => 'Subject',
            'your-message' => 'Message',
        ));
    }

    function merge_handler_cf7($key) {
        $submission = $this->pass_vars[0];
        $data = $submission->get_posted_data();
        return isset($data[$key]) ? $data[$key] : '';
    }
}

iw_add_trigger_class('IW_CF7Submit_Trigger');

Required Methods

Method	Description
`trigger_when()`	Hook into a WordPress action to listen for the event
`get_title()`	Name shown in the recipe editor
`get_contact_email()`	Return the email of the user involved in the event

Inside your event handler, you must:

Set $this->pass_vars with the event data
Call $this->trigger() to fire the recipe system

Optional Methods

Method	Description
`get_desc()`	Short description shown below the title
`get_log_details()`	Text saved to the trigger log for debugging
`merge_fields()`	Define custom merge fields for the admin picker
`merge_handler_{name}($key)`	Resolve a merge field value at runtime
`custom_condition($recipe_id, $configs)`	Extra filtering at the trigger level
`admin_public_note($recipe_id, $configs)`	HTML displayed in admin (e.g., webhook URL)

Optional Properties

Property	Type	Default	Description
`$is_advanced`	`bool`	`false`	Show in “Advanced” section of trigger selector
`$is_hidden`	`bool`	`false`	Hide from trigger selector
`$merge_handlers`	`array`	`[]`	Merge field group handlers
`$install_conditions`	`array`	`[]`	Condition class names shown as “recommended”
`$install_actions`	`array`	`[]`	Action class names shown as “recommended”

Tips

Your trigger class must extend IW_Automation_Trigger
The $this->trigger() call handles everything: user identification, condition evaluation, action execution, and logging
$this->pass_vars is an array that conditions and actions can access via $trigger->pass_vars
Merge field handlers receive the field key and should return the resolved value
Always call iw_add_trigger_class() at the bottom of the file