Webhook Triggers Quickstart Guide
Limited Preview: Webhook Triggers & Listener
Webhook Triggers and the Webhook Listener are currently in Limited Preview and may change without notice. Access is invite-only. Self-nomination form is here. Production use is approved but may be subject to interruptions or breaking changes.
Learning Objectives
In this Quickstart guide, you'll build an Ambient Agent that its triggered by a webhook and notifies the user with a message based on the provided webhook payload. As part of the building process you'll learn how to:
- Build a Listener to receive webhooks.
- Create a Compound Action that enables an AI Agent to handle the incoming webhook and generate a message to the user.
Prerequisites
- Access to the "Agent Studio" app.
What You'll Build
The plugin you will build solves a common, practical problem: notifying users about specific updates or action items.
Before starting to build, we always recommend that you first map out the desired end user experience and the overall building blocks of an Ambient Agent.
Here is an example of the end-user experience we hope to enable:

To get to this experience, the Ambient Agent will consist of one Compound Action and two input arguments: the user's email and the payload of the webhook:

You'll build an end-to-end working Ambient Agent Plugin via these phases:
- Set up a Listener.
- Build the Compound Action, containing two actions and two input arguments.
- Add the Listener and Compound Action to your AI Agent by launching a Plugin.
- Test your webhooks using our Purple Suite tool.
Let's get started!
Phase 1: Set Up Your Webhook Listener
-
Navigate to the App Picker in the top right corner. Click on "Agent Studio"."
-
Navigate to a new Listener.
-
Click "Create".
-
Set the following Title and Description for your listener (be sure to replace firstnameand lastname with your corresponding information).
Field Value to enter (replace "first" & "last" with your info) Title quickstart_first_last_notification_listener
Description Listens for simple notifications
-
Click "Copy URL" and paste the webhook URL somewhere you can get back to it quick, we will need it in future steps.
-
Click "Publish" to save your listener.
Phase 2: Create Your Compound Action
You will now create a compound action to handle the incoming webhook routed by the listener.
In this phase you will build a compound action with 1) user_email
and payload
input arguments, and 2) two actions to resolve the by email and then notify them with the message. Here's a reminder of the bird's-eye view for our Compound Action

-
Navigate to a new “Compound Action” in the left nav and then click “Create”.
-
Set the following title and description for your Compound Action (be sure to replace "firstname" and "lastname" with your corresponding information).
Field Value Title quickstart_first_last_message_notification_ca
Description Sends a message to a user
-
Copy the following expression into the Compound Action Editor
steps: - action: output_key: target_user action_name: mw.get_user_by_email input_args: user_email: data.user_email - action: output_key: generate_text_action_result action_name: mw.generate_text_action progress_updates: on_complete: ON_COMPLETE_MESSAGE on_pending: ON_PENDING_MESSAGE input_args: system_prompt: '''Based on the provided user message, provide an actionable alert and formatted message for the user''' user_input: RENDER(): template: "{{webhook_data}}" args: webhook_data: $STRINGIFY_JSON(data.payload) - notify: output_key: notification_output recipient_id: data.target_user.user.id message: data.generate_text_action_result.openai_chat_completions_response.choices[0].message.content
Understanding the Compound Action
This Compound Action executes three actions in sequence, with the output of one step feeding into the next:
mw.get_user_by_email
(Built-in Action)- Purpose: To identify the notification recipient.
- Process: It takes a user's email address (from the webhook) as its input and retrieves that user's unique Moveworks profile ID.
mw.generate_text_action
(Built-in Action)- Purpose: To create a polished message for the user.
- Process: This action uses an LLM to interpret the raw data in the webhook payload and generate a structured, readable message.
notify
(Compound Action Expression)- Purpose: To send the final notification.
- Process: This action takes two inputs from the previous steps:
- Recipient ID: It uses the user ID that was retrieved by the
mw.get_user_by_email
action. - Message: It uses the formatted text that was generated by the
mw.generate_text_action
action.
- Recipient ID: It uses the user ID that was retrieved by the
-
Define two formal input arguments to represent the
user_email
andpayload
inputs that this Compound Action Requires-
Click on the "Input Args" button near the top right corner
-
Click "Create New" in the "Input Arguments" pop up.
-
Fill out the following details for your
user_email
argument:Field label Value to enter/select Argument Name user_email
Data Type Select "string" Description The email of the user that will be notified
Required Check the box -
Hit "Save"
-
Click "Create New" again to the "Input Arguments" pop up.
-
Fill out the following details for your
payload
argument:Field label Value to enter/select Argument Name payload
Data Type Select "object" Description The payload of the webhook sent from an extenral system
Required Check the box -
Hit "Save" and hit the "X" icon to close this "Input Arguments" pop up.
-
-
Click "Publish"
All done with Actions!You're ready to move on — time to create your Plugin and put everything you've built together.
Phase 3: Configure and Launch Your Plugin
This section guides you through adding your Listener and Compound Action to a Plugin. A key step will be configuring the data flow, where you'll specify exactly which fields from the webhook you want to forward to your action.
-
Navigate to a new Plugin (navigate to the library and click "Create").
-
Set the following title and description for your Plugin (be sure to replace "firstname" and "lastname" with your corresponding information).
Field Value to enter Title quickstart_first_last_message_notification
Description Sends a message to a user based on a webhook with an email and payload.
-
In the “Workflow Overview” section click “System” in the Trigger box.
-
Configure your system trigger to connect your Listener in the slide-out pop up with:
Field Label Value to enter/select Select Trigger Type Webhook
Select Listener quickstart_first_last_notification_listener
(Select yours)Event Filter Leave this field empty -
Click on the "Body" in the "Workflow Overview
-
Configure your system body to connect your compound action to the plugin
Field label
Value to enter/select
Select Type
System body
Select an Action
quickstart_first_last_message_notification_ca
(Select yours)Input mapping
user_email: parsed_body.email
payload: parsed_body.data
Understanding the Input Mapping
When the listener receives a webhook, we expect a JSON payload structured like this:
{ "createdAt": "2025-09-02T18:10:28Z", "data": { "actions": [ { "text": "View PTO Policy", "url": "https://internal-hr.example.com/policies/pto-2025" } ], "alert_code": "PTO-EXP-WARN-90", "details": { "accrual_policy": "use-it-or-lose-it", "current_balance_hours": 112.5, "hours_at_risk": 72.5, "policy_id": "pol_hr_pto_standard_2025" }, "last_date": "Tue Sep 09 2025", "message": "This is a friendly reminder that you have accrued paid time off that is set to expire. To ensure you don't lose these hours, please schedule and take your vacation time.", "object": "alert", "priority": "medium", "title": "Action Required: Use Your PTO Balance Before Year-End" }, "email": "[email protected]", "eventId": "evt_alert_2b3c4d5e6f7G8h9I0jK", "eventType": "alert.pto_expiration_warning" }
The listener automatically parses this JSON payload into a
parsed_body
object. To access the data you need, you simply use dot notation to reference the keys:parsed_body.email
parsed_body.data
This method gives you the flexibility to extract only the specific data your compound action requires, even if the webhook sends a much larger payload.
Note: While this mapping is currently a manual process, we are developing an "Auto Configure" feature to streamline this setup in the future.
-
-
Define your Launch Configuration
-
Navigate to the "Launch Configuration" tab
-
In the Input field under "Allow selected users", enter your email (or multiple emails using commas to separate the email addresses).
-
-
Click "Publish" to launch your Plugin.
And just like that — you've finished building your Plugin, and now it's ready to use!Congrats! You are not ready to test your plugin. In the next section, you will provided with required tools to help you test it.
Phase 4: Testing
This section guides you through the Moveworks Purple API tool to help you test your plugin by sending webhooks to your listener.
-
Go the Moveworks Purple API Tool
-
Click "Create New Session ID"
-
Click on the "Webhooks" Tab
-
Configure the field values with your listener information
Field Value to enter Webhook URL Enter the Webhook URL you created in Phase 1 API Key Leave empty -
Select the "Simple Notification" tab and click on "Generate Webhook Payload"
-
A payload will be generated for your upcoming webhook
{ "createdAt": "2025-09-02T18:10:28Z", "data": { "actions": [ { "text": "View PTO Policy", "url": "https://internal-hr.example.com/policies/pto-2025" } ], "alert_code": "PTO-EXP-WARN-90", "details": { "accrual_policy": "use-it-or-lose-it", "current_balance_hours": 112.5, "hours_at_risk": 72.5, "policy_id": "pol_hr_pto_standard_2025" }, "last_date": "Tue Sep 09 2025", "message": "This is a friendly reminder that you have accrued paid time off that is set to expire. To ensure you don't lose these hours, please schedule and take your vacation time.", "object": "alert", "priority": "medium", "title": "Action Required: Use Your PTO Balance Before Year-End" }, "email": "[email protected]", "eventId": "evt_alert_2b3c4d5e6f7G8h9I0jK", "eventType": "alert.pto_expiration_warning", "sessionId": "C7KOA5KoumkgsTiXDHa4" # This sessionId will be based on your session }
-
Change the
data
andemail
fields to the corresponding values you would want.
-
-
Click on Trigger Webhook
Success! Check Your NotificationsExcellent work! You have successfully tested your plugin. Check your chat, where you should now see a notification from the AI Assistant containing the message from your webhook payload.
Reflecting on this Plugin
The plugin you just created uses several key Agent Studio concepts, from Webhook Listeners to Compound Actions. You've successfully built a plugin that:
- Listens for webhooks from other apps.
- Grabs only the specific data it needs from the webhook payload.
- Processes that data to find the right user and send them a direct message.
Awesome work sticking with it! Your plugin is now ready to notify users of important messages and updates.
Updated 1 day ago