Custom Events trigger automation workflows via API and pass additional data for personalization. Each event can include custom fields, such as tracking numbers, product details, or review links, for use in workflow content.
While standard triggers (such as Placed Order or Abandoned Cart) cover common events, Custom Events let you automate unique actions like review submitted or gift card created that go beyond Omnisend’s built-in triggers.
Before You Begin
When you integrate your store with Omnisend, a set of standard events becomes available, including Subscribed to Marketing, Placed Order, and Abandoned Cart. If you want to trigger a workflow for a different type of action, you’ll need to use a Custom Event.
Custom Events can be:
Created manually via API, or;
Added automatically through integration with a third-party app.
Omnisend supports and recommends using only API v5 for Custom Events. Earlier versions, like v3, are still functional but are no longer actively supported.
If you haven’t worked with APIs before, we strongly recommend involving a developer to help set up Custom Events.
API documentation explains how the integration works, but a developer is best equipped to implement it correctly using the provided technical details.
Custom events only appear in the automation trigger dropdown after they've been triggered at least once.
Custom events require an identified contact (email or phone number) to work. Anonymous visitors will return a 400 error.
💡 Examples of Custom Events Added by Third-Party Tools
AfterShip: Info Received – Triggers the workflow when an order is shipped.
Custom fields: tracking number, tracking URL.
Intercom: Review Created – Triggers the workflow when a contact leaves a comment for a support agent.
Custom fields: rating, review content.
Growave: Wishlist Back in Stock – Triggers the workflow when a wishlist item is back in stock.
Custom fields: product details.
Junip: Review Created – Triggers the workflow when a product review is submitted.
Custom fields: product info, review submission link.
Create a Custom Event
For the Custom event to start working, you will need to add it to your Omnisend account and set it up on the third-party side.
Step 1. Access Custom Events.
Navigate to Store Settings → API → Custom events → Click Create custom event to get started.
Step 2. Set Up via API Documentation.
You’ll be redirected to the API documentation, where your developer can complete the setup and create the Custom Event. Here, you need to:
Select v5 as the API reference version;
Navigate to Events API → Events → Send Customer event.
Step 3. Copy the API Key.
Go to Store Settings → API → Create API key and copy your API Key.
Step 4. Add API Key to Header.
In the API documentation, select Header and paste your API Key into the Header field.
Step 5. Complete Body Params.
Follow the wizard to enter the required event details:
Contact – You must include at least one contact identifier: an email address or phone number of a contact you want to pass the event with.
You can also include additional data such as address, tags, birthdate, or custom properties. These are stored on the contact profile and persist over time.
Event ID – For example,
60ba330da4a60c8ed682c5bd:Event name – For example,
Review submitted;Event time -Optional. If used, it must be a past or present date. Future dates will cause the event to fail.
Event version - Optional. Can be left empty for Custom Events.
Origin - This should always be set to
"api"Properties (optional) – Add any additional data to personalize your workflow (see example structure below).
Once complete, click Try it to create the event.
Step 6. Test Your Event.
Verify event creation:
Check for a 200 status code in the API response after clicking "Try it."
Go to Store Settings → API → Custom events to confirm the event appears in your list.
If you encounter errors, check Store Settings → API → API logs for details.
💡 Fire a test event:
Use the POST /events endpoint to trigger the event manually. This makes it appear in automation triggers.
Important Notes:
To edit a Custom Event, you must delete the existing event and create a new one using the API documentation.
Disabling a Custom Event will stop it from functioning, and any automations using it as a trigger will be discontinued.
Re-enabling a Custom Event does not automatically reactivate the associated workflow. You must re-enable the automation manually.
Deleting the API key created for the Custom Event will cause your event to fail.
Add Event Properties
Properties (also labeled as custom fields in Omnisend) pass additional data with each event (e.g., product name, tracking URL, review rating). This data can be used in workflow filters, split conditions, and message personalization.
To add Event Properties, go to Properties → Properties Object. Enter the property name and its value. To include additional properties, click Add field, then enter the next property name and its value.
Once your custom event is passed to Omnisend, you can review the synced event properties by going to Store Settings → API → Custom Events.
Click on the event name to view the associated custom fields.
Note: Once the custom event syncs to Omnisend, event properties appear in the interface as custom fields. These terms refer to the same data; the only difference is the label used, depending on whether you're viewing them in the API documentation or within Omnisend.
Important Notes:
Property names are internal labels used to reference the data in automations and message personalization.
Property names cannot be changed after the event is created. To update a property name, delete and recreate the event.
Property values can change over time by sending new events with updated values.
Example: If a contact leaves a 1-star review, send an event with
reviewType: "1 star". If they later update it to 2 stars, send a new event withreviewType: "2 stars".
You cannot pass multiple values in a single property (e.g.,
"1 star, 2 stars"). Send one event per value change.The only supported value type for property fields is string.
💡 We recommend consulting your developer or third-party integration provider to determine the correct data format for each custom field.
Use Custom Events in Automation
Step 1: Create a Workflow.
Go to Automations → Create workflow → Create from scratch.
In the trigger dropdown, find your Custom Event.
Step 2: Configure Workflow Settings.
Once you add the Custom Event trigger, all workflow settings populate with data from the event:
Trigger filter – Filter by custom field values (these are the event properties you defined via API).
Split block – Branch workflows based on custom fields.
Step 3: Personalize Message Content
You can use custom fields data to personalize the content of your messages, including Email, SMS, and Push Notifications.
If you're passing a link as an event property, you can also use it with a button in your email.
Use Unsubscribe Link in Automation
When using a Custom Event to trigger an automation workflow, the footer content block includes an unsubscribe link by default.
We recommend including this link in all messages. However, it is not required if the message is transactional (e.g., related to an order the customer placed).
Important: Automation workflows triggered by Custom Events will send messages to unsubscribed contacts by default. If you do not want to message unsubscribed contacts, update the Workflow Channel Settings by clicking the trigger block and adjusting the preferences.
Troubleshooting
Issue 1: Custom event doesn't appear in automation trigger dropdown.
This is expected since events appear in automation triggers list only after being triggered at least once.
Use the POST /events endpoint to trigger the event manually. This makes it appear in automation triggers.
Example API call (v5):
POST https://api.omnisend.com/v5/events
Headers:
X-API-KEY: your-api-key
Content-Type: application/json
Body:
{
"origin": "api",
"email": "[email protected]",
"eventName": "Product Back in Stock",
"fields": {
"productName": "Blue Widget",
"productURL": "https://yourstore.com/products/blue-widget"
}
}
Issue 2: Getting a 400 error when triggering the event.
A 400 error indicates a payload-related issue, meaning the request sent to Omnisend is invalid. These errors originate from the sender’s side, not from Omnisend.
To resolve this, go to Store settings → API → API logs and review the 400 errors.
💡 You can use the drop-down filter to display only 400-level errors.
Issue 3: Shopify Flow custom fields not appearing.
Shopify Flow uses a different endpoint and JSON structure from the standard Omnisend API, so custom fields may not appear as expected.
To resolve this:
Use the
##{{}}template variable syntax when mapping fields in Shopify Flow actions.Ensure field names match exactly as defined in Store Settings → API → Custom events (they are case-sensitive).
Keep in mind: Shopify Flow events do not appear in the API logs in Omnisend, as this is expected behavior.
For full setup instructions, refer to the Integrate Shopify Flow with Omnisend article.
Issue 4: Event was working, now it's not firing.
If your event suddenly stops triggering:
Go to Store Settings → API → Custom events to check if the event is still enabled.
If the event was deleted, you’ll need to recreate it and update any workflows using it as a trigger.
Review API logs under Store Settings → API → API logs for recent errors or failed requests.
FAQ
Why does the API documentation call them "event properties" but Omnisend calls them "custom fields"?
This is a terminology difference between the API documentation and the Omnisend interface. When you create event properties in the API documentation, they sync to Omnisend and are displayed as custom fields in automation workflows, triggers, splits, and message personalization. Both terms refer to the same data: the additional information passed with each custom event.
What’s the difference between Contact Custom Properties and Event Properties?
Contact custom properties are stored on the contact profile and persist over time. They're passed using the
customPropertiesobject inside thecontact objectblock of the event payload. These values are visible on the contact profile and can be reused across campaigns, automations, and segmentation.Event properties, on the other hand, are passed in the
propertiesblock of the event. They're tied only to the event that was triggered, labeled as custom fields, and do not persist on the contact profile. These are useful for event-specific conditions, such as filtering by product name, review score, or order total within automation workflows.
Can I edit the names of event properties after creating an event?
No. Property names cannot be changed once the event has been created. If you need to rename a property, you'll need to delete the existing event and create a new one with the updated property name.
Note: Deleting an active event will disable any workflows that use it as a trigger.
Which API version should I use for Custom Events – v3 or v5?
Use v5: https://api.omnisend.com/v5/events and include "origin": "api" in your request body.
While events created in the UI are compatible with both v3 and v5, v5 is the current standard and recommended for all new implementations.
Can I pass URLs in event properties?
Yes. URLs can be passed as string values in event properties. They can be used in automation filters, split conditions, segmentation rules, or directly in message content using personalization variables like [[event.referralLink]].
For further assistance with custom events, don't hesitate to reach out to us at [email protected] or in-app chat.