An event-based trigger subscribes a workflow to a named PayMongo event. When an event with the matching name (and any additional filter keys) is published, the Workflow API starts a new instance and passes the event payload as the workflow input.

The model

flowchart LR
    A[PayMongo event payout.deposited]
    B[Trigger condition matches?]
    C[New instance]
    A -->|publish| B
    B -->|match| C
    B -->|no match| Z[ignored]

Condition shape

The condition is a JSON object on the request body. It must include event_name. Any additional keys become filters: the trigger only fires when every filter key matches the corresponding field on the event.

{
  "event_name": "payout.deposited",
  "livemode": true
}

A condition that omits both event_name and schedule is rejected as invalid_request_body.

Examples

Subscribe to payout.deposited

curl --request POST 'https://workflow-api.paymongo.com/v1/triggers' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow_id": "wf_abc123",
    "condition": {
    	 "event_name": "payout.deposited",
    	 "channel": "paymongo"
    }
  }'

The response carries the persisted trigger:

{
  "id": "trg_xyz",
  "workflow_id": "wf_abc123",
  "state": "pending",
  "condition": {"event_name": "payout.deposited"},
  "livemode": true,
  "created_at": "...",
  "updated_at": "..."
}

The trigger transitions from pending to active once the underlying subscription is confirmed.

Filter by an additional field

Run the workflow only for live-mode payouts on a specific organization plan:

curl --request POST 'https://workflow-api.paymongo.com/v1/triggers' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow_id": "wf_abc123",
    "condition": {
      "event_name": "payout.deposited",
      "livemode": true,
      "plan": "enterprise"
    }
  }'

If any of the three keys do not match the published event, the trigger is silent.

What the workflow sees

When the trigger fires, the event payload becomes the workflow's input. Workflow steps can reference the payload as ${input.<field>} or, for nested fields, ${input.<path.to.field>}. See Variables and Expressions.

Updating and deleting

PUT /v1/triggers/:id updates the workflow_id or the condition. Switching from event-based to schedule-based (or back) is not allowed. To change types, delete the trigger and create a new one. The error code is trigger_type_change_forbidden.

DELETE /v1/triggers/:id soft-deletes the trigger. It will no longer fire. To inspect previous fires, use Trigger Executions.

See Also

• Schedule-Based Triggers: the cron-based alternative.
• Auto-Direct Payouts on Events: a production pattern using payout.deposited.
• Create a Trigger: full request and response reference.