Flowable message and signal events: setup guide

Flowable message and signal events: when processes must react to outside events

A Flowable process often has to stop and wait until something outside it happens: a payment settles, a partner calls back, or another internal system finishes its batch. Message and signal events are the BPMN mechanisms for that wait. A message event is addressed to one specific process instance or a specific process definition, while a signal event is broadcast to every process that is listening for that signal name. Choosing between them is the first design decision, and it determines who can wake the process and how many instances respond at once. Message start events create a new instance when a message arrives, and message catch events hold an existing instance in a waiting state until a matching message is correlated to it.

Flowable's open source engines are Apache 2.0 Java engines for BPMN, CMMN, DMN and the event registry, exposed through both Java and REST APIs, so the same event can be delivered from application code or from an HTTP call. The Flowable docs describe how an engine is embedded in a Java SE application, a servlet container, a Spring application or a Java EE server, and that choice affects how your callback endpoint, transaction and thread handling are built. Before you commit to a design, confirm the exact correlation rules, the event API methods and the signal scope behavior in the Flowable documentation for the version you plan to run, because these details are version-specific.

Plan the inbound path before you draw the model. Decide which business key or correlation value your partner or upstream system can send back, how duplicate or late messages will be handled, and who owns the endpoint that receives them. Your team should also confirm which scope a signal reaches in your deployment and whether tenant boundaries apply to it. If the outside world sends events in a shape the process does not expect, a correlation failure can leave a token waiting indefinitely, so add a timeout path and a monitoring check for instances that stay parked on a catch event.

Message or signal: choosing the event type

A message event is a point-to-point signal aimed at one waiting process instance. The sender identifies the instance through a correlation key, usually a business identifier such as an order number or a case reference, and the engine delivers the message only to a matching waiting catch event. Use a message when the sender knows which instance should continue and the event carries information meant for that one case of work. A signal event is a broadcast. It is thrown once and every subscriber in scope that is waiting for that signal name reacts, whether that is one instance or many.

Targeting: A message needs a correlation key that matches a waiting subscription. A signal does not need a key and reaches every matching subscriber.
Delivery when nothing waits: A message sent with no matching subscription is typically rejected or missed, so the sender must handle that outcome. A signal thrown with no subscribers is simply not received by anyone.
Payload: Messages are commonly used to pass variables for one instance. Signals are better suited to announcing a state change that many processes may need to know about.
Sender knowledge: Choose a message when the sender must know a specific instance exists. Choose a signal when the sender should not need that knowledge.
Operational risk: A broadcast can wake many instances at once, so confirm how many subscribers a signal could reach before modeling it.

Before committing to either type, write down the intended receiver for each event and confirm the matching rules with the Flowable BPMN documentation for your version.

Configuration options and when each fits

This table compares the Flowable mechanisms for receiving outside events, from message starts and catch events to signals and the event registry. Read each row for the situation it fits and the trade-off you accept, then confirm the exact API behavior against the Flowable version you deploy.

Option	When it fits	Main trade-off
Message start event	An external event should create a new process instance, such as a claim submitted by another system.	Each delivery can start an instance, so duplicate messages need a check in your design before the engine runs.
Message intermediate catch event	A running instance must pause until a specific business event arrives, such as a payment confirmation.	The instance waits in the database, so you must plan for messages that arrive early, late or never.
Message correlation through the runtime API	Your application knows the business key or correlation keys and must resume a specific waiting instance.	Correlation depends on keys you set consistently, and a wrong or missing key leaves the message unmatched.
Signal start event	One event should start every process definition that listens for it, across several models.	Signals are broadcast, so unrelated definitions can react, which makes ownership of signal names important.
Signal intermediate catch event	Many waiting instances should react to one notification, such as a policy change announced to all open cases.	Every matching waiting instance is affected, so scope and tenant boundaries must be checked before throwing.
Signal throw event	A process step must notify other waiting instances from inside the model.	The throwing instance does not receive a direct reply, so the result must be tracked through variables or other records.
Tenant-scoped signals	Your deployment serves several tenants on one engine and signals must stay within one tenant.	Tenant handling must be confirmed for each signal path in your version, and a mistake can reach the wrong tenant.
Event registry	Events come from outside the process engine as structured events and should drive cases or processes through channels you define.	It adds a separate component to design, deploy and monitor, so confirm it fits your version and team skills first.

How message correlation finds the right waiting instance

When a message arrives, Flowable does not look for a process definition. It looks for a waiting execution that matches the message name and the correlation values you supply, such as a business key, a process instance ID or a set of variables. A message catch event only receives a message if exactly one suitable execution is waiting for that message name under those values. This is why correlation design matters more than the message itself: the engine matches what you pass in, so the keys your application sends must identify one waiting instance and nothing else. Confirm with the Flowable docs for your chosen version which correlation parameters are supported for message correlation and how the engine behaves when no execution or more than one execution matches.

Ambiguous correlation is where messages go missing or land in the wrong case. If two instances share a business key, or a correlation variable such as an order number is reused across customers, a message can be delivered to the wrong instance or fail to find any instance because the sender believed the key was unique. Some correlation failures surface as errors to the caller, while others are only visible in logs or in the database, so your integration must check the result of every correlation call rather than assume delivery. Design unique business keys with a documented format, avoid reusing identifiers that are valid across the business, and decide in advance which field is authoritative when a message carries several keys.

Messages from brokers and external systems are often delivered more than once, and senders retry after timeouts. Your application needs an idempotent handling rule: record each incoming message identifier, and make the handler safe to run twice so a repeated message does not complete a task again, start a second instance or move a case forward. Plan for a message that arrives before the instance reaches its catch event, since it may fail to correlate and need a retry or a holding step, and for a message that arrives after the instance has already moved on. Test these cases with duplicate, late and unmatched messages before go-live, and agree with the business owner what should happen to each one.

Setting up message and signal events in your stack

This sequence takes message and signal events from naming and scope decisions through deployment, API exposure and tenant verification, so each event has a defined sender, a defined receiver and a tested way to reach the right process instance. Each step ends with a check you can record before moving on.

Define event names and scope in the design
Architects and process owners list every message and signal the processes must wait for or broadcast, and record the name, direction, sender system and whether the event is meant for one instance or for every listener. Signals are broadcast to all matching subscriptions in their scope, so a signal that should reach only one case needs a different design than one that should reach every waiting process. The step is done when each event has a written name, owner and scope, and the team agrees on a naming convention that other systems can follow without guessing.
Model message start and catch events in BPMN
Process modelers add message start events for processes that begin from an outside message, and intermediate message catch events where a running instance must pause for one. Each event references a message definition whose name matches the design list, and the team checks that no two processes start from the same message name unless that overlap is intended. The check is a deployed model in a development environment whose diagram shows the expected message name on every start and catch event.
Decide correlation keys before coding
Before any sender is built, the team decides which business key or process variable identifies the waiting instance, such as an order number or application ID, and which variables the message carries. Correlation keys must be unique enough that one message cannot match the wrong instance, and the team should decide what happens when no instance matches. The check is a short correlation table, reviewed by the owner of each sending system, that lists the message name, key field, expected variables and the response for zero or multiple matches.
Deploy definitions through the pipeline
Engineers deploy the BPMN models through the same pipeline used for other process definitions, so the message and signal definitions move between environments with the code that depends on them. Deployment should be run in a staging environment that matches production database and configuration choices. The check is that the deployed definitions appear in the engine's repository with the expected version, and that a test start from the message start event creates one new instance.
Expose the correlation API with authentication
Engineers expose the Flowable REST API or a wrapper service that lets external systems send messages and signals, and place it behind the same authentication and network controls used for other internal APIs. Access should be limited to the systems that legitimately send each message name, since the engine does not decide which caller is allowed. The check is a security review that confirms unauthenticated requests are rejected and that a caller without rights for a given message name cannot correlate to it.
Test correlation and duplicate delivery
QA engineers send matching messages, non-matching messages, repeated messages and messages sent before the catch event is reached, then record how the engine and the wrapper respond. Duplicate handling depends on the sender's retry behavior and on how the application records processed message IDs, so the team should test both the engine result and the business outcome. The check is a test report that shows one instance advanced per intended message, with a defined outcome for every rejected or duplicate case.
Verify subscriptions and tenant behavior
Operations and platform engineers query the running engine for open event subscriptions, confirm that each waiting instance holds the expected subscription, and check how signals and message names behave across tenants. Signal scope and tenant scope are separate decisions, so a signal sent in one tenant should be tested to confirm it does not reach instances of another tenant. The check is a signed-off subscription report for a test tenant pair, plus a note of any tenant behavior that the team has confirmed with the Flowable documentation or its own testing rather than assumed.

Security and operational risks of outside events

Message and signal endpoints accept input from outside the process, so each one needs an owner for authentication, integrity, tenant boundaries, monitoring and evidence. The engine correlates and stores events, but it does not decide who may send them or whether a message is genuine, so these cards map each risk to the part of the design that must handle it.

Authenticating callers of event APIs

The Flowable REST application and Java API will accept a message or signal correlation from any caller that reaches them unless you place authentication in front of the endpoint. Decide which services may send which message names, then enforce that at your gateway or in a wrapper service that calls the engine. Check that default accounts are removed and that no event endpoint is reachable from networks that should only see internal services.

Guarding against forged messages

The engine trusts the message name, correlation keys and variables it receives, so a caller that knows a correlation key can move another customer's process forward. Validate payloads against a schema, bind correlation keys to values the caller already holds, and reject events that arrive for instances in a state they should not be in. Where the sender is an external system, verify its signature or mutual TLS identity before the message reaches the engine.

Replay and duplicate handling

Brokers and retrying senders can deliver the same message twice, and a replayed message can repeat a payment step or approval if the process still waits for it. Give each external event a unique identifier, store processed identifiers, and make the receiving process idempotent. Confirm with your team how the engine responds when a correlation finds no waiting subscription, and test that path explicitly.

Tenant isolation for signals

A signal broadcasts to every process definition that catches it, and tenant-scoped signals limit that reach only when the tenant identifier is set and checked consistently. Confirm that signal names are not shared across tenants by convention alone, that start events and boundary events filter by tenant, and that a tenant administrator cannot raise a signal that affects another tenant's instances. Test this with two tenants holding identically named process definitions.

Monitoring waiting subscriptions

A message catch event that never receives its message leaves an instance waiting indefinitely, and nothing in the process itself alerts anyone. Build reports of instances that have waited past an agreed age, count unmatched events, and track failed or locked jobs in the async executor. Pair these with the monitoring endpoints your Spring Boot or REST deployment exposes, and agree who acts on each alert.

Logging events as audit evidence

When an outside event changes a regulated decision, you need to show which event arrived, from which system, when it was accepted and what the process did next. The engine's history records the correlation, but it does not record your caller's identity or raw payload unless you capture them. Write an inbound event log with sender, timestamp, correlation key and outcome, and set retention to match your records policy. Ask your compliance lead which fields an auditor will request.

When the event registry is the better choice

Choose the Flowable event registry instead of BPMN message or signal catch events when the event volume or the number of event sources is large enough that a process model would become the wrong place to receive them. A BPMN catch event waits inside a single process instance for a correlated message or a broadcast signal. That works well for a process that waits for one approval, one payment confirmation or one callback. It works poorly when a stream of events from a broker or an external system must be filtered, enriched and then used to start or advance many cases and processes. In that situation, the event registry engine, which Flowable describes as part of its engine set, is the component that receives events, evaluates them against event definitions and triggers the matching work. The 7.0.0 release notes list the event registry among the engines kept in scope, so it is available in the current major line.

Before you commit to that design, confirm the integration points in the Flowable docs for your version, because the registry's inbound channels, supported transports and event payload handling are not something to assume from the BPMN event model. Check how an event definition is deployed, how it correlates an incoming event to a case or process, and what happens when no instance matches. Also confirm whether the registry requires any extra database or runtime components in your environment, since those affect your deployment and operations plan. The Flowable open source page is the starting point for the engine set, but the detailed behavior belongs in the version-specific documentation.

A useful check is to write down, for each event type, who produces it, how often it arrives, whether it should start new work or advance existing work, and what must be recorded if it is dropped or duplicated. If most events advance a single known instance and volume is modest, keep the BPMN catch event, because the model stays readable and the message correlation is visible in the process diagram. If many event sources feed several cases or processes, or the same event must reach multiple definitions, plan for the registry and assign an owner for event definitions as a governed artifact in the same way you govern process deployments.

Limits to confirm in your environment

Message and signal events depend on details that change between Flowable versions, databases and cluster layouts. The cards below list the limits to verify in your own environment before you commit to an event design, so that the design you test is the one you run.

Event semantics and scope by version

Confirm how message and signal events are matched, which scope they apply to, and whether a signal reaches every running instance or only those listening at the moment it is thrown. Check these rules against the Flowable version you will deploy, not against examples from older versions. Record the behavior in a short test suite that runs on every upgrade candidate.

Async executor behavior across nodes

Timers and asynchronous jobs that resume waiting processes run through the async executor, which uses lock owners and lock expiration times in the database. Confirm how your cluster nodes claim and release these jobs, and test what happens when a node stops mid-job. Message delivery that depends on a job may be delayed until another node recovers the lock.

Database support for timing precision

Event correlation and job scheduling store timestamps, so the database type and version affect ordering and timing. The Flowable configuration docs list the supported databases and note that MySQL versions below 5.6.4 lack millisecond precision. Confirm your database version and its time handling before you rely on timing-sensitive event logic.

Message ordering assumptions

Messages sent to the same process instance can arrive out of order when callers retry, run in parallel or pass through a broker. Decide which messages must be processed in sequence, and design correlation keys and completion conditions so that a late or duplicate message does not move a process into an unexpected state. Test duplicate and reordered delivery explicitly.

Payload size and variable limits

Event payloads become process variables, and large values increase database load, history volume and serialization cost. Agree a maximum payload size with the teams that send events, and store large documents outside the engine with only references in variables. Confirm the variable types your serialization setup accepts before you publish a message contract.

Event API changes during upgrades

Upgrades can change the Java and REST interfaces that send messages and signals, and the Java and Spring baseline they run on. Review the release notes for each target version, rerun your event tests against the new engine, and confirm that in-flight waits still correlate after the upgrade. Plan the upgrade with the same care as a schema change.

Questions teams ask before building event-driven Flowable processes

What does an event-driven Flowable integration cost, and what drives the effort?

The cost comes from the number of event types, the correlation logic, the number of systems on each side, and the testing needed to prove that the right instance wakes up under real traffic. Flowable's open-source engines are licensed under Apache 2.0, so the software itself carries no license fee, but you still pay for infrastructure, engineering time and any partner work. Effort rises when messages arrive out of order, when one business key maps to several process instances, or when events must cross tenants. Ask any quote to itemize design, build, testing, deployment and handover separately, and to state which parts recur, such as support or upgrades.

How long does it take to scope a message or signal event integration?

Scoping depends on how many events exist, how well the source systems document them, and whether the owners of those systems can answer questions quickly. A small set of inbound messages with clear identifiers can be scoped in a short workshop, while a set spread across several teams and brokers takes longer because each contract needs agreement. DeployOpen plans most work as fixed-scope engagements, with scope, deliverables and timelines agreed in writing before work starts. Ask for the scoping outputs to be listed: an event inventory, correlation keys, error paths and an acceptance test plan.

What must our team provide before a partner can build event handling?

Your team needs to supply four things: event contracts that name each message or signal, its payload fields and its owner; stable identifiers such as a business key or correlation ID that both sides can read; access to non-production environments that match production in configuration; and a decision on who may publish each event. Without a documented correlation key, the process cannot find the waiting instance reliably. Tenant boundaries, retention rules for event payloads and the approval path for changing a contract also need named owners before build starts.

Can an in-house team build Flowable message and signal events without a partner?

Yes, if the team already runs Java services and has someone who understands BPMN semantics, the Flowable APIs and the database that stores the execution state. The harder parts are rarely the API calls. They are handling duplicate messages, messages that arrive before the process reaches its catch event, and signals that wake more instances than intended. A team building in-house should write tests for those cases, run a load test that matches expected volume, and agree on an operations runbook. Flowable's documentation covers the core APIs, so the main question is whether your team has the time and skills to test these edge cases well.

When is it worth bringing in a partner for event-driven processes?

A partner is worth considering when the event landscape spans several brokers or business units, when processes must survive audit scrutiny, or when your internal team lacks capacity for both delivery and operations. A partner also helps when a Camunda 7 or Activiti estate must move to Flowable while active instances are still waiting on messages. Flowable's engineering blog describes in-place migration from those engines, and its free LEAP tool reports ahead of time what a migration involves. Ask a partner to show how they will test correlation, handle failures and hand over runbooks, not only how they will write the process model.

How does the way we design events affect future Flowable upgrades?

Event names, correlation keys and the variables passed with each message become a contract between your systems and the engine, so changes to them ripple into running instances. Major Flowable releases change the baseline. Version 7.0.0 moved to Java 17, Spring Boot 3 and Jakarta EE, and version 8.0.0 moved to Spring Framework 7 and Spring Boot 4 without backward compatibility for Spring Boot 3. Keep event names versioned, avoid embedding framework-specific classes in payloads, and record which process definition versions can receive each message. Confirm the upgrade path for your exact version before you commit to a design.

Should we use message and signal events or the event registry for external input?

Use message and signal events when the process model itself should wait for or react to an outside event, and use the event registry when events arrive at high volume and must be routed to cases or processes through separate event definitions. Signal events broadcast to every matching waiting instance, which is useful for announcements but risky when scope is wider than intended. Check the Flowable documentation for the exact scoping and tenant behavior of your version, and test a sample of real correlation patterns before you choose. Your architecture review should record the decision and the reason.

How DeployOpen scopes and supports Flowable event integrations

DeployOpen plans, implements, tests, documents and supports Flowable message and signal events inside your own infrastructure, using the open-source engines under Apache 2.0. Engagements are fixed-scope, so the event contracts, correlation rules and handover material are agreed in writing before the build starts.

How we scope

Inventory which processes wait for outside messages or signals, and which systems send them
Agree correlation keys, tenant boundaries and signal scope in a written design before development
Confirm which events belong in the event registry instead of BPMN catches, with the reasons recorded

How we build

Implement message start and catch events, correlation calls and signal throws against the agreed contract
Write tests for duplicate messages, late messages and messages that arrive before the waiting instance exists
Configure tenant-scoped signal handling and verify that signals do not reach processes in other tenants

How we hand over

Deliver the event catalog, correlation key reference, payload schemas and a runbook for failed correlations
Document the Flowable version and database used, and the steps to confirm event behavior after an upgrade
Train your engineers on the test suite so they can extend event handling without us

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing
Retainer work can cover new event sources, changes to correlation rules and review of version upgrades
Ask for the support scope, response expectations and upgrade testing included in any quote before signing

Flowable message and signal events