Triggers and event payloads

The trigger defines when a published workflow may start and what initial context it receives.

Magento event triggers

The builder catalogue lists registered Magento events by area. Search for the exact event name, select it and confirm the event identifier on the trigger card. Event coverage depends on the installed Magento modules and the events they dispatch.

Mapped events produce a normalized payload. For a customer-save event, the payload includes a customer entity with fields such as customer ID, email, first name, last name and group ID. Sales-order events expose an order entity with fields such as increment ID, state, status, grand total and customer reference.

Do not assume that an arbitrary Magento model field is present in every event payload. Use the trigger's mapped entity fields or inspect a privacy-safe recent run before writing a condition.

Choose the entry path

The practical entry paths are Magento events and two authenticated REST operations. The trigger node in the published definition must match the way the process is started.

The runtime accepts start-node aliases such as manual_trigger, schedule_trigger, webhook_trigger, provider_event_trigger and raw_event_trigger in imported definitions. Those aliases do not create a separate public callback or recurring scheduler. To run on a timetable, use a monitored external scheduler or Magento integration that calls the API trigger. To receive a webhook, call the authenticated API trigger route and enable the signature requirement on the trigger node.

Choose one entry path that owns the business start. Two published definitions may listen to the same Magento event, but each creates its own independent run.

Magento event scope

An event trigger may apply to every store or only selected store views. The selected event names and store IDs are copied to the trigger registry when the definition is published. Editing the draft does not change live matching until the new version is published.

The event consumer creates the run asynchronously. If no run appears, check the exact event identifier, active version, store scope and workflow.event.trigger.consumer before inspecting later workflow nodes.

API and provider payloads

The API trigger stores the supplied payload object as the run payload. The provider endpoint accepts an event name, event data and provider. Magento sales-order and customer events receive their normalized entity structure when a matching mapper is available. Other provider events use the generic event structure.

Both endpoints enforce the configured request-size and payload-field limits. They return an accepted flag plus the numeric and public run identifiers. Acceptance means that Magento created and queued the run. The run-start consumer still has to execute it.

Signed inbound requests

API and webhook-style trigger nodes can require an extra signature. The caller sends:

• X-Workflow-Timestamp, containing the current Unix timestamp;
• X-Workflow-Nonce, containing a new value for this request;
• X-Workflow-Payload-Sha256, containing the SHA-256 hash of the serialized payload;
• X-Workflow-Signature, containing the HMAC-SHA256 signature.

The signature input is workflow_code|timestamp|nonce|payload_hash, signed with the secret stored on the trigger node. Magento checks the configured lifetime and clock tolerance, verifies the optional payload-hash header, and rejects a nonce that was already used. Keep the secret out of workflow names, screenshots, logs and source control.

Payload structure

Magento-mapped events use the following broad structure:

{
  "workflow_event": {
    "schema_version": 1,
    "provider": "magento",
    "event_name": "customer_save_after_data_object"
  },
  "event": {
    "name": "customer_save_after_data_object",
    "provider": "magento"
  },
  "entity": {
    "entity_type": "customer",
    "customer_id": 24,
    "group_id": 2
  },
  "data": {}
}

Treat run payloads as business data. Access to payload display is protected by a separate Admin permission, and API credentials should receive only the permissions their integration needs.