> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldvisagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Workflow

> Learn how WorldVisa workflows are triggered using the Event API, including per-subscriber triggers, attaching context and payload data, and sending to multiple subscribers.

Triggering a workflow starts the execution of a notification pipeline in WorldVisa. A workflow is triggered when an event is sent to WorldVisa.

When a workflow is triggered, WorldVisa resolves the target subscribers, evaluates workflow logic, and executes each configured step to deliver notifications across the selected channels. Trigger requests can include payload data, context, or identify multiple subscribers, allowing you to control both who receives the notification and what data is available during execution.

## Test with a real subscriber

A real subscriber already exists in the same environment, with the `subscriberId` your app uses and the channel fields the workflow needs, such as `email`.

1. Create the subscriber on the Subscribers page, or pass their profile on the trigger.
2. Open the workflow and click **Test workflow**.
3. Select that subscriber, fill the payload, and send.
4. Open the [Activity Feed](https://docs.worldvisagroup.com/developers/workflow/monitor-and-debug-workflow.md) and filter by that subscriber ID.

Connect an active email provider and store the recipient address on the subscriber before testing email delivery. An Inbox test needs the `<Inbox />` component initialized with the same application identifier and `subscriberId`.

## Trigger Event API

Trigger a workflow from your backend by sending an event to the WorldVisa API. An event represents an action in your system, for example, an order created or a comment added, and is mapped to a workflow using the workflow’s trigger identifier.

Call `POST ${WV_API_URL}/v1/events/trigger` with the environment secret key. Never put that key in frontend code. The REST field for the workflow identifier is `name`. A workflow must be published before a Production trigger can run it. If the subscriber does not exist yet, passing `to` as an object [creates them on that trigger](https://docs.worldvisagroup.com/developers/concepts/subscribers.md#just-in-time).

When you trigger an event, you specify:

* The workflow to execute.
* The subscriber (or subscribers) the notification is intended for.
* The payload data used to personalize notification content.

At a minimum, triggering a workflow requires the workflow trigger identifier and a subscriber identifier.

```bash theme={null}
curl -X POST "${WV_API_URL}/v1/events/trigger" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflow_identifier",
    "to": {
        "subscriberId": "string"
    }
}'
```

> [!NOTE]
>
> For full request options and response details, see the Trigger Event API reference.

Once the event is received, WorldVisa executes the workflow, evaluates step conditions, resolves variables, and delivers notifications across the configured channels.

From here, you can extend event triggering by attaching context data, targeting multiple subscribers using topics.

## Trigger a workflow with context

You can attach context data when triggering a workflow using the Event API. Context can be referenced from existing contexts created in the WorldVisa dashboard by providing the context type and identifier or defined inline at trigger time. Any context passed with the event is available to all downstream steps and channel templates during workflow execution.

When you pass a rich context object with a `data` field, WorldVisa upserts the stored context `data` if the context already exists - similar to subscriber fields on the `to` object. Passing only a string identifier references the context without changing stored `data`.

Context data is passed using the `context` object in the trigger request.

```bash theme={null}
curl -X POST "${WV_API_URL}/v1/events/trigger" \
  -H "Authorization: ApiKey ${WV_API_KEY}" \
  -H "Content-Type: application/json" \
  -H 'Accept: application/json' \
  -d '{
    "name": "workflow_identifier",
    "to": [{ "subscriberId": "string" }],
    "context": {
      "context_type": "context_identifier",
      "region": "us-east-1",
      "app": "dashboard"
    }
  }'
```

> [!NOTE]
>
> To learn how contexts work and how to manage them, see the [Context documentation](https://docs.worldvisagroup.com/developers/workflow/advanced-features/contexts/contexts-in-workflows.md).

## Send to several subscribers

Pass an array of subscriber IDs or subscriber objects in `to`. Resolve group membership in your backend; [Topics](https://docs.worldvisagroup.com/developers/concepts/topics.md) explains the current API boundary.


## Related topics

- [How do subscribers work in WorldVisa?](https://docs.worldvisagroup.com/developers/concepts/subscribers.md)
- [Multi-tenancy](https://docs.worldvisagroup.com/developers/concepts/tenants.md)
- [Notification Workflows in WorldVisa](https://docs.worldvisagroup.com/developers/workflow.md)
- [Push](https://docs.worldvisagroup.com/developers/integrations/push.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.