< woml />
View on GitHub

Internal Events

An event trigger subscribes a workflow to a named fact. One event may start every active workflow with the same exact event name.

Subscribe

WOML
<event id="orderCreated" name="order.created" secret="{{secrets.EVENT_CONTROL_TOKEN}}">
  <schema>{ "type": "object", "required": ["orderId"] }</schema>
</event>

Event names use at least two lowercase segments. A schema is optional. Add secret to expose authenticated HTTP publication; omit it for internal-only publication.

Publish internally

JavaScript
return services.events.emit("order.created", {
  orderId: context.payload.orderId
}, { name: "publish-order-created" });

Publish from an application

With a secret configured, POST to /_woml/events/order.created with a bearer token and stable Event-ID. WOML may accept all, some, or none of the subscribers depending on their schemas and admission policies.

See Publish an Event for workflow-to-workflow patterns.

Understand why events exist

An event represents a fact that may interest zero, one, or many workflows: order.created, customer.verified, or content.published. The publisher does not wait for subscriber results and does not need to know which workflows are active.

This differs from a workflow call, which targets one workflow and waits for its final JSON result.

Build two subscribers

Both workflows can declare:

WOML
<event id="orderCreated" name="order.created">
  <schema>
    {
      "type": "object",
      "required": ["orderId"],
      "properties": {
        "orderId": { "type": "string" }
      }
    }
  </schema>
</event>

Activate both files in one runtime:

Terminal
woml run workflows/

Publishing once fans out independently to both exact-name subscribers. Each subscriber gets its own run ID, policies, schema validation, and durable outcome.

Publish from a workflow

JavaScript
const publication = await services.events.emit(
  "order.created",
  { orderId: context.steps.createOrder.id },
  { name: "publish-order-created" }
);

return { publication };

Use a stable operation name so the managed effect has clear durable identity.

Publish from an application

Add a secret reference to at least one subscriber, store the token, and call the printed control URL with both a bearer token and a stable Event-ID. Repeating the same event identity and payload is deduplicated; reusing the identity with different data conflicts.

The publication result may be accepted by all subscribers, some subscribers, or none. A schema or runtime policy can reject one subscriber without invalidating every other subscriber.

Avoid event request-response coupling

Do not publish an event and then poll subscribers for one answer when the business requirement is synchronous. Use services.workflows.call() for request-response composition. Events are best for facts, fan-out, and loose coupling.