Skip to main content

​
Overview

SuprSend provides two distinct methods to trigger notification workflows: Event-Based Triggers and Workflow API Triggers. Both ultimately invoke the same workflow engine, but they differ in coupling, control, flexibility, and failure semantics. Choosing the right approach (or mixing both) depends on your architecture, notification type, and operational requirements. This guide lays out how each method works, when to prefer one over the other, and what trade-offs to keep in mind.

​
How Each Method Works

​
Event-Based Trigger

Your system publishes an event to SuprSend via backend SDK, frontend SDK, HTTP API, or a third-party CDP like Segment. The event carries a distinct_id (identifying the user), an event_name, and a properties payload with relevant data. SuprSend receives the event and checks if any live workflow is linked to that event name. If matched, SuprSend takes over — resolving the recipient from the user profile, computing target channels based on preferences, and executing the workflow.
Key characteristic: Your code knows what happened, not which workflow to run. The mapping from event to workflow(s) lives entirely in the SuprSend dashboard.

Check Send and Track Events doc for implementation details.

​
Workflow API Trigger

Here, you explicitly call a workflow using its workflow_slug, specifying the workflow and recipients directly in the API request. You control the full payload — including inline user and channel information if needed.
Key characteristic: Your code knows exactly which workflow to run and who should receive it. The mapping is explicit in code, not inside the dashboard.

Check Trigger Workflow from API doc for implementation details.

​
Comparing both methods

DimensionEvent-Based TriggerWorkflow API Trigger
CouplingLoose — code emits events, SuprSend maps to workflowsTight — code references workflow_slug directly. If there’s a mismatch in workflow slug on dashboard vs code, trigger fails. Treat workflow_slug as a stable API contract
User pre-creationMandatory — event is silently discarded if user doesn’t existNot mandatory — supports defining recipient inline (acts as UPSERT). Also supports anonymous/transient recipients via is_transient: true
Recipient resolutionEither pass the recipient’s distinct_id directly in the event call, or override recipient in workflow trigger settings on the SuprSend dashboard to resolve the actual recipient from event properties (you’ll need to pass a dummy recipient distinct_id in this case)Recipients (user or object) are specified explicitly in the API request payload
Object triggersSupported via override recipient — point to an event property containing the object_type and object_idSupported natively — pass object_type and object_id directly in the recipients array. Recommended approach for sending to non-user entities like objects
One event → multiple workflowsYes — a single event can fan out to many workflowsNo — each API call targets one workflow
Payload schema validationSupported - validates event properties with the defined schema and throws error in the API response if validation failsSupported - validates workflow data with the defined schema and throws error in the API response if validation fails
Who controls workflow mappingProduct/ops team via dashboardEngineering team via code
Adding new notificationsDashboard-only change if added on an existing eventRequires code change for every new notification
CDP/Segment integrationNative fit — events flow through your existing data pipeline (Segment, Rudderstack, etc.)Not applicable

​
When to Use Event-Based Triggers

Event-based triggers are the right choice when:
  • Your architecture is event-driven. If you already publish domain events to a bus (Kafka, RabbitMQ, Segment) or use a microservices architecture where services communicate via events, adding SuprSend as a consumer is natural. You don’t need to add notification-specific API calls into your service code.
  • Notifications map cleanly to user actions. For user-initiated events — POST_LIKED, COMMENT_ADDED, ORDER_PLACED, FRIEND_REQUEST_SENT — the event model is intuitive. The event already exists in your system; you just need to forward it to SuprSend.
  • You’re already syncing users to SuprSend. If you have a separate user sync pipeline (e.g., for storing preferences, channel info), events are a clean fit. User creation/update is decoupled from the notification trigger.
  • You want product teams to iterate independently. Because the event-to-workflow mapping lives in the SuprSend dashboard, product or ops teams can add new notification workflows, change routing logic, or adjust channels without requiring engineering deployments.
  • One event should fan out to multiple workflows. For example, an ORDER_PLACED event might trigger an order confirmation to the buyer, an alert to the seller, and an internal notification to the ops team — all from a single event.
  • You’re integrating via a CDP. If you use Segment, Rudderstack, or similar platforms, you can route events from your CDP directly into SuprSend. This avoids adding another integration point in your backend.

​
Watch Out For

  • Silent failures. If the user doesn’t exist in SuprSend already, the event is silently discarded. There’s no error returned to the caller. You’ll need to monitor SuprSend logs or set up webhook callbacks to detect these.
  • User sync reliability is critical. If your user sync fails for a user, all future event-triggered workflows for that user will fail silently. Build retries with backoff into your user sync pipeline — treat it as a critical dependency, not a fire-and-forget job.
  • Not ideal for critical alerts. Since anyone with dashboard access can modify or disconnect event-to-workflow mappings, critical notifications (e.g., OTP delivery, payment confirmations) could break without engineering awareness. For high-stakes alerts where reliability is non-negotiable, prefer Workflow API triggers where the mapping is controlled in code.
  • Debugging complexity. When a notification doesn’t fire, the root cause could be at multiple layers: event not sent, event sent but user not found, or workflow not linked to the event. The indirection adds debugging surface area.

​
When to Use Workflow API Triggers

Workflow API triggers are the right choice when:
  • You don’t want to maintain a separate user sync. This is the biggest advantage. You can define users inline — it acts as an UPSERT function. Pass distinct_id with channel info, and SuprSend creates or updates the user as part of the trigger. No separate sync pipeline to build, monitor, or retry.
  • You’re sending system-generated or scheduled notifications. Daily digests, weekly reports, batch billing reminders, scheduled maintenance alerts — these originate from backend jobs, not user actions. There’s no natural “event” to emit; you’re programmatically deciding to notify.
  • You need to send to anonymous or transient users. OTP verification, magic link sign-in, or notifications to users who haven’t signed up yet. The Workflow API lets you pass is_transient: true with inline channel info, so no prior user creation is needed.
  • You’re migrating existing notifications to SuprSend. If you have an existing notification system and want to incrementally move workflows to SuprSend, the Workflow API is the path of least resistance. You replace your existing send calls with SuprSend API calls — no need to refactor your system into an event-driven model or set up user syncing first.
  • You want engineering control over what triggers. Every trigger is an explicit API call in your codebase. This means triggers go through code review, are version-controlled, and can’t be accidentally modified via the dashboard.

​
Watch Out For

  • Tight coupling. Your code references specific workflow_slug values. Renaming a workflow on the dashboard doesn’t change its slug, but if a workflow is deleted and recreated with a different slug, your code breaks. You’ll need coordination between dashboard changes and deploys.
  • No fan-out. Each API call triggers exactly one workflow. If a single business event should trigger multiple workflows, you need to make multiple API calls. Consider creating a helper/wrapper to manage this.
  • More code changes for new notifications. Adding a new notification type always requires a code change and deployment, even if it’s added to an existing flow.
  • User profile duplication risk. When you pass recipient details inline (e.g., email, phone), this data gets upserted to the user profile in SuprSend. If the same user is also being synced via a separate pipeline, the two sources can conflict — the API trigger may overwrite profile fields with stale or incomplete data, or vice versa.

​
Hybrid Approach: Using Both

In practice, most teams end up using both methods depending on the notification type.
Notification TypeRecommended Trigger
User action notifications (likes, comments, purchases)Event
Transactional notifications requiring tight coupling with code (OTP, password reset)Workflow API
Scheduled / batch notifications (digests, reports)Workflow API
Notifications to anonymous usersWorkflow API
Notifications to objects (departments, teams, topics)Either — Workflow API for direct targeting, Event via override recipients when object ID is in event data
Notifications integrated via CDP (Segment, Rudderstack)Event
Notifications where product team needs to iterate quicklyEvent
Critical-path notifications where silent failure is unacceptableWorkflow API

​
Best Practices

​
Idempotency

Both methods support idempotency_key. Always use it for critical notifications to prevent duplicate sends on retries. SuprSend deduplicates requests with the same key for 24 hours.

​
Payload Validation

Both event properties and workflow API payloads support runtime validation via JSON schemas. Schema Validation catches payload mismatches at the API level before the workflow executes.

​
Testing

Design and test workflows in staging before cloning to production. For event-based triggers, verify that the event name and properties match what the workflow expects. For API triggers, validate the full payload shape against the workflow’s template variables. You can also enable test mode in staging to redirect all notifications to test users while testing.

​
Observability

All workflow executions appear in Executions tab in SuprSend’s logs regardless of trigger method and their corresponding messages appear in Messages tab. For event-based triggers, also check for discarded events (due to missing users or unlinked workflows) in requests logs. Check logging doc for more details.

​
Bulk Operations

Use bulk APIs for high-volume sends. For broadcasting to a large list of users, use the Subscriber List Broadcast API instead of looping over individual triggers. SuprSend recommends lists and broadcast for audiences larger than 1,000 users.

​
Summary

Event-based triggers optimize for decoupling and agility — your code stays clean, product teams iterate independently, and your event-driven architecture extends naturally into notifications. The trade-off is less control in code and a dependency on users being pre-created. Workflow API triggers optimize for control and reliability — synchronous feedback, no user sync needed, support for anonymous and object recipients, and full engineering ownership. The trade-off is tighter coupling and more code changes for notification updates. Use both, with clear team conventions on which method applies to which category.