When a custom trigger plugin is the right way to start a Dify workflow
A team wants an incident, ticket, deal or alert in an internal system to start a Dify workflow without someone pressing run. A custom trigger plugin is the mechanism for this: it listens for events from the source system and starts a workflow when one arrives. The Dify documentation describes triggers as a plugin category alongside tools, models and other types, so the trigger plugin is what connects an external event source to a workflow. Confirm the exact trigger lifecycle, event payload handling and subscription behavior against the Dify version you run, because trigger support has changed across releases and the Dify releases page lists the minor versions that shipped it.
Build a custom trigger plugin when your event source has no official plugin, or when the official one does not expose the events, filters or authentication your process needs. Teams in ticketing, CRM and monitoring usually find that a generic webhook is not enough: they need to map a specific event type to a workflow input, verify that the sender is trusted and decide which records should be ignored. If a single scheduled run or a manual start meets the need, a trigger plugin adds maintenance work you may not need. Whether a trigger is the right plugin type, compared with a tool or an agent strategy, is covered on the plugin type page, so this section assumes the choice is already narrowed to triggers.
Before writing code, list the events you need, the systems that emit them, and who owns the credentials each system uses. Ask your source system vendor which webhook or subscription options it supports, whether it signs requests, and how it retries failed deliveries, because those answers decide whether Dify receives each event once, more than once or not at all. Plan the public trigger endpoint as part of the build, since the trigger depends on Dify receiving inbound calls from outside your network. Your security team should review that exposure early, and the endpoint must be reachable only from the sources you name.
What a Dify trigger plugin does in a self-hosted deployment
A trigger plugin connects an external event source to a Dify workflow. The pieces below form one chain: an event arrives, its payload is mapped to workflow inputs, the public endpoint accepts it, and the plugin daemon runs the code that handles it. Each part is a place where a self-hosted team makes a decision and where failures tend to appear.
Receiving external events
The plugin must accept calls from the ticketing, CRM or monitoring system that produces the event. Decide whether the source pushes events to Dify or whether the plugin polls the source, since each choice changes what must be reachable from outside your network. Confirm how the source signs or authenticates its requests and whether it retries failed deliveries, because retries can start duplicate workflow runs.
Mapping payloads to workflow inputs
Event payloads from monitoring tools and ticketing systems vary in shape and include fields you may not want in a prompt. Define which fields become workflow inputs, which are dropped, and how missing values are handled. Keep the mapping in version control next to the plugin code so a change in the source schema is reviewed rather than discovered in a failed run.
Exposing the public trigger endpoint
A trigger receives calls from outside the Dify network, so the endpoint is the most exposed part of this module. Place it behind your reverse proxy with TLS, restrict it to the source systems' addresses where possible, and reject unauthenticated requests. Review how the endpoint interacts with the SSRF proxy and internal network boundaries before go-live.
Packaging and installing the plugin
A trigger plugin is packaged, installed and versioned like other Dify plugins. Decide how the package reaches your instance, who approves it, and how upgrades replace it without breaking workflows that already depend on its trigger. Record the Dify version you tested against, since the plugin architecture changed in 1.0 and later releases may alter plugin behavior.
Running the plugin daemon
The plugin daemon runs the plugin code separately from the API service, so its health, timeouts and resource limits determine whether events are handled. Confirm how the daemon restarts after a crash, what happens to events received during an outage, and where its logs are collected. Test a burst of events in staging before relying on the trigger for production alerts.
Decisions to settle before writing the trigger
This table compares the six decisions that shape a custom trigger plugin: how events arrive, how they are authenticated, how they reach Dify, how payloads become inputs, how duplicates are handled and how the plugin is distributed. Read each row with your operators in mind, because each choice changes what they must configure, monitor and approve.
| Decision | Options | When it fits and what it changes for operators |
|---|---|---|
| Event source | Webhook push from the source system, or polling a source API on a schedule | Push fits ticketing, CRM and monitoring tools that can call out on change. Polling fits systems that cannot send events but expose a change feed. Polling adds outbound traffic and a schedule to operate, while push needs a reachable inbound endpoint. |
| Authentication of inbound events | Shared secret or signature check on each request, or a source-issued token validated by the plugin | Use the signing method the source supports and verify it before any workflow starts. Operators must store the secret in Dify's credential handling and rotate it in both systems together, or events will fail silently. |
| Public endpoint exposure and network path | Dify endpoint reached directly through the reverse proxy, or through a gateway or allowlisted network path | Public exposure is needed when the source sits outside your network. Restrict source IP ranges where the source publishes them and confirm which path requests take through Nginx and any gateway. Confirm with your security team before opening any inbound route. |
| Payload-to-input mapping | Map fields in the plugin code to fixed workflow inputs, or pass the full payload as one text input | Fixed mapping suits stable schemas and keeps prompts predictable. Passing raw payloads is quicker but pushes parsing into prompts and raises the risk of sensitive fields reaching models. Document the schema and version it with the plugin. |
| Idempotency and duplicate events | Use the source event ID to skip repeats, or accept duplicates and make workflows safe to rerun | Sources often retry deliveries, so the same event may start a workflow twice. Storing processed event IDs needs a persistence layer and a retention rule. Confirm each source's retry and delivery guarantees before choosing. |
| Plugin distribution | Marketplace, GitHub release, or local .difypkg file | Marketplace listing suits broadly shared plugins, which is rarely true for internal event sources. GitHub or local .difypkg fits private plugins, and keeps signature checks on in production. Each option changes how upgrades reach every instance. |
How a trigger plugin moves from design to production
This sequence takes a trigger plugin from a confirmed Dify version and written event contract to a tested, signed package running first in staging and then in production. Each step produces an artifact that the next step depends on, so the sequence can be audited.
Confirm the Dify version and plugin architecture
Confirm the Dify version your deployment runs and check that the plugin architecture and plugin daemon in that release support trigger plugins as your team expects. Read the release notes and upgrade guide for the target version, because minor releases arrive roughly monthly and the plugin interfaces can change between them. The output is a short compatibility record that names the Dify version, the daemon configuration, and the SDK version the plugin will be built against. Done means a second engineer has reviewed the record and it is stored with the project.
Design the event contract and payload mapping
Write an event contract that lists each event type the source system sends, the fields the workflow needs, which fields are sensitive, and how each field maps to workflow inputs. Define the event identifier used for deduplication, the signature or shared secret the source uses, and the response the endpoint returns for rejected or malformed events. Agree the contract with the owner of the ticketing, CRM or monitoring system. Done means the contract document is approved and every mapped field has a named owner and a test sample taken from the source system.
Build and test the plugin locally
Implement the trigger in the plugin project, following the plugin development structure for the Dify version you confirmed. Keep credentials in the plugin's credential schema rather than in code, and limit outbound calls to the systems the contract names. Run the plugin against a local Dify instance and replay recorded sample events from the source. The output is a local test log showing that each sample event starts the expected workflow with the expected inputs, and that malformed events fail without starting a run.
Expose the trigger endpoint through the chosen network path
Decide how the source system reaches the public trigger endpoint, for example through your existing reverse proxy, a dedicated ingress, or a controlled tunnel. Confirm that TLS terminates where your security standards require, that only the trigger path is exposed, and that the rest of the Dify console and API stay on internal networks. Check the SSRF proxy and outbound rules so the plugin can still reach the internal systems it needs. Done means a reachability test from the source system succeeds, a request to any other path is denied, and the network diagram is updated.
Verify duplicate and failed-event handling
Test what happens when the source sends the same event twice, when a workflow run fails after the trigger fired, and when Dify or the plugin daemon is unavailable during delivery. Confirm the deduplication key from the contract prevents a second workflow run, and confirm that the source's retry behavior does not create a flood of runs. Record which failures the source retries and which are dropped, and decide where dropped events are logged. The output is a failure test matrix with observed results and the owner who accepted each residual risk.
Package and distribute the plugin
Package the tested plugin as a distributable file and choose the distribution channel your organization approved, such as a private repository or a local package. Version the release, record the checksum, and sign the package if your production policy requires signature checks, keeping those checks enabled in production. Store the signed package, the release notes and the test matrix together. Done means the package installs on a clean staging instance from the distribution channel alone, with no local files copied in.
Roll out to staging, then production
Install the signed package in a staging workspace that mirrors production settings, then run the replayed event set and a live event from a non-critical source record. Review the logs for run creation, inputs, errors and the outbound calls made by the plugin. Once staging results match the test matrix, schedule the production install, keep the previous version available for rollback, and monitor the first live events closely. Done means production runs match staging behavior and the rollout record names the approver, the version and the rollback path.
Why the public trigger endpoint needs the most review
A trigger plugin only works if the source system can reach an endpoint that Dify exposes, so the trigger endpoint is the part of this design that most widens the attack surface of a self-hosted Dify. Every event source that calls in is an untrusted caller until your controls say otherwise, and the endpoint sits on the path to workflows that may call internal tools and models. Treat its review as a separate workstream from the plugin code itself, and settle the exposure decision before any build work starts.
Dify documents several platform controls that bear on this path, but none of them replaces inbound design. The SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, which limits what a workflow can reach on the way out, not who can call in. SECRET_KEY signs session cookies and JWTs and changes to it log out users, so it must be stored and rotated deliberately. The 1.16.1 release notes describe token-based API authentication between services, agent sandbox network isolation through a Squid proxy and sandboxed Jinja2 template rendering. Confirm how each of these applies to your chosen version, because event payloads are attacker-influenced input that can reach templates and tool calls.
Inbound protection for the trigger endpoint is the team's design responsibility. Decide the reverse proxy controls in front of Dify, such as which paths are published, TLS termination, source address restrictions where the source system allows them, request size limits and rate handling that sheds floods without dropping legitimate bursts from monitoring tools. Define how each source authenticates, how secrets are issued per source and rotated, and how replayed or malformed events are rejected. Before go-live, confirm these items in your own environment: the exact endpoint paths your version exposes, how the plugin validates signatures, and whether your network team can enforce the proxy rules you specify.
What drives the effort and cost of a trigger plugin
This table lists the factors that change how much work a custom trigger plugin takes and who carries it. Read each row as a question to answer in the written scope, since the quote follows from those answers. The main takeaway is that the number of source systems, their authentication model and how events are delivered usually matter more than the Dify side of the build.
| Driver | What changes the work | Who carries it and what keeps it down |
|---|---|---|
| Number and type of source systems | Each ticketing, CRM or monitoring system has its own event model, webhook behavior and admin setup, so each adds a separate mapping and test set. | The vendor's team or your administrators configure the source, and the partner builds one handler per source. Start with one system and a single event type. |
| Authentication the source supports | Signed webhooks with a shared secret are simpler than OAuth flows or per-tenant tokens that must be refreshed and stored. | Your identity or platform team issues and rotates credentials, and the plugin verifies signatures. Confirm the signing method each source offers before the build starts. |
| Payload complexity and mapping | Nested JSON, optional fields and custom fields in a CRM or ticket make the output schema and input mapping larger. | The builder maps fields into the workflow's variables. Agree on a small, stable payload contract with the workflow owners before coding. |
| Retries and deduplication | Sources often resend events after timeouts, so the trigger must recognize repeats and avoid starting the same workflow twice. | The plugin or a shared store holds event IDs and a short memory window. Ask the source how it identifies events and how long it retries. |
| Network exposure requirements | The trigger endpoint must be reachable from the source, which may require an inbound route through your gateway, TLS and an allowlist of source addresses. | Your network and security teams open and monitor the route. Keep the public surface to the trigger endpoint only and review it under your security hardening standards. |
| Distribution and signing model | A plugin installed in one workspace is simpler than one distributed to many workspaces with signed packages and version pinning. | Your platform team decides the release channel and signing policy. Confirm how your Dify edition and plugin policy handle unsigned packages before distribution. |
| Testing across Dify upgrades | Minor Dify releases arrive roughly monthly, and plugin interfaces can change between versions, so each upgrade may need a regression run. | The partner or your team reruns event tests in a staging instance before each upgrade. Keep a replayable set of sample events for this purpose. |
How the trigger plugin connects to the rest of the platform
Which workflow does a trigger start, and how does event data reach it?
The trigger plugin starts a workflow that the app builder has bound to the trigger, and the event payload enters that workflow as the inputs the trigger declares. Design the first nodes around the fields your ticketing, CRM or monitoring system actually sends, then run a test event and confirm which values reach each input node before any model or tool node runs. Keep field mappings explicit so that a renamed field in the source system fails visibly during testing. Confirm the exact binding behavior for your Dify version in the Dify documentation, because workflow start conventions have changed between releases.
What does the plugin daemon do for a running trigger plugin?
The plugin daemon loads the installed trigger plugin package and executes its code, so the handler that receives events and any subscription logic run there, separately from the main API service. Because the daemon is a separate process, its resource limits, request timeouts and package size limits decide whether a burst of events is processed or dropped. Check those settings for your version before go-live, and confirm how the daemon authenticates to the API service, since that shared credential is part of the trust boundary between the two. Restarting the daemon after a plugin update is a routine step you should rehearse.
Why does the reverse proxy and TLS sit in front of the trigger endpoint?
Source systems can only call a trigger if it has a stable HTTPS address that they can reach, so the reverse proxy, typically the Nginx service in the Docker Compose layout, publishes that path and terminates TLS. Expose only the trigger path that the source system needs, not the whole console, and keep the certificate chain complete so that the calling system accepts it without workarounds. Confirm which forwarded headers the proxy sets and which ones Dify trusts, because a wrong client address or scheme breaks signature checks and logging. Renew certificates on a schedule that someone owns.
How does the SSRF proxy affect calls from a trigger to internal systems?
When a trigger workflow calls an internal ticketing, CRM or monitoring API, that outbound request passes through the SSRF proxy configured with the SSRF_PROXY settings. The proxy is designed to block internal and private IP ranges, which protects the platform from being used to reach hosts it should not, but it also means your internal targets will fail until you deliberately allow them. Plan the specific hosts and ports the trigger needs, add them through the proxy configuration your version supports, and test each one. Keep the allowlist narrow and record who approved each entry. Confirm the current variable names in the environment variable reference.
How do SECRET_KEY and the secret store protect trigger credentials?
SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials stored in Dify, so any credential the trigger saves in the platform depends on it. Set it once during deployment and keep it in your secret manager, because changing it after deployment logs out all users and can make previously stored encrypted values unusable. Workspace encryption keys can be stored locally or in Azure Key Vault, which lets you choose where the key material lives. Decide before go-live who holds the key, how it is backed up with the database, and how a restore would recover it. Test that recovery path, not only the happy path.
What must be configured in the source system's webhook or API?
The source system needs the trigger's public HTTPS URL, a shared secret or signing method for each event subscription, and a filter that limits deliveries to the event types the workflow handles. Configure the retry behavior and the delivery timeout on the source side, and decide what happens when Dify is unavailable, since the source may queue, retry or drop events. Run a test delivery and confirm that a rejected signature produces a clear log entry on both sides. Verify the signature inside the trigger plugin code as well, because the endpoint is reachable from outside your network. Document the owner of each subscription.
What the client should receive at handover
The handover is a set of artifacts that let the client's team rebuild, verify and operate the trigger plugin without DeployOpen. Each card covers one artifact, and together they connect the source code, the event contract, the network path, the test record and the ongoing runbook.
Plugin source and version history
The complete plugin repository, including the plugin manifest, the trigger provider and handler code, dependency lock files and a changelog that maps each released version to the Dify version it was tested against. Ask for the build steps so the client can produce the same .difypkg package without a DeployOpen engineer. Confirm that the repository lives in the client's own source control, not only in a DeployOpen account.
Event contract and payload mapping
A written contract for each event type the trigger accepts, listing the source system, the event fields, which fields become workflow inputs and how missing or renamed fields are handled. Include an example payload from each source system, marked as a sample from the test environment. Check that the contract names an owner on the client side who approves changes to it.
Endpoint and network configuration
The public trigger endpoint's address, the reverse proxy or gateway rules in front of it, TLS configuration and the allowlist of source systems permitted to call it. Document how the endpoint reaches the Dify API service and which outbound paths the SSRF proxy must allow for any callbacks the workflow makes. Ask for a diagram that shows every hop from the source system to the workflow run.
Duplicate and failed event test evidence
Recorded test runs showing how the trigger behaves when the same event is delivered twice, when a payload is malformed, when the workflow fails midway and when the source retries after a timeout. Each test should state the expected result, the observed result and the log lines or run identifiers that prove it. Ask which idempotency key is used and how it is stored.
Distribution and signing record
A record of how the packaged plugin was distributed to each environment, including the package version, the checksum, the signing step and who approved the release. Confirm that production keeps signature checks enabled and that the signing key is held by the client or in a store the client controls. Note any environment where the plugin was installed from a local file rather than the agreed channel.
Operations runbook for upgrades and key rotation
A runbook covering how to upgrade the plugin and the Dify release it depends on, how to rotate the endpoint credential and the signing key, and how to disable the trigger during an incident. Include the backup step to take before each upgrade, the rollback procedure and the checks to run afterward. Ask the team to rehearse one rotation in a non-production workspace before go-live.
How DeployOpen scopes and delivers a trigger plugin
DeployOpen plans, builds and hands over event-driven triggers for self-hosted Dify inside your own infrastructure. We start from the source systems that emit events, agree the trigger contract and the public endpoint in writing, then deliver the plugin, its tests and the runbook your operators need.
How we scope
- Inventory the ticketing, CRM or monitoring events that should start workflows, and the systems that send them.
- Agree which event fields, signing method and delivery guarantees the trigger plugin must handle.
- Record the public trigger endpoint exposure, network path and ownership in the written scope before work starts.
How we build
- Build the trigger plugin against your chosen Dify plugin type and the Dify version you run in production.
- Validate incoming payloads, reject unsigned or replayed requests and test behavior with recorded sample events.
- Test the public endpoint behind your reverse proxy, including TLS, rate limits and failure handling for bad payloads.
How we hand over
- Deliver the plugin package, source, configuration reference and the endpoint settings your team must keep.
- Document the event contract, sample payloads, the steps to rotate signing secrets and the rollback procedure.
- Walk your operators through installing the plugin, reading trigger logs and diagnosing missed or duplicate events.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ask about how the plugin will be re-tested when Dify releases a new minor version, since releases arrive roughly monthly.
- Ongoing support, upgrades and continuous testing are available as a retainer, and the quote follows from the written scope.
