🚧

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.

Step-by-Step Instructions

Phase 0: Pick a Use Case

Maybe you already have an event-driven use case in mind which you want to build for a customer or prospect. If so, great! Follow along the guide below to build it out.

But if you don’t have a specific use case in mind or you just want a very simple example to build your knowledge, I recommend you follow the step-by-step instructions to set up the Notify on New GitHub Issue use case:

Notify on new GitHub issue

• What it does: Whenever a new issue is opened in a specific GitHub repository, Moveworks sends a notification with the issue details.
• Requirements: You have a Github account with at least one repo.

Phase 1: Set Up Your Webhook Listener

1. In the top right-hand corner click on “Agent Studio”

   

   
   

2. Click on the new “Listeners” icon in the left-nav. The click “Create”.

   

   
   

3. On the Listener creation page add a Name and a Description. Suggestion:

   1. Name: yourmwid_GitHub_Issue_Trigger_Test
   2. Description: Listener for GitHub issues on my repo

4. Click “Copy URL”. (You’ll need to add this into the webhook provider app. GitHub in our case). Click “Validate”. Then click “Publish”.

   

   👉

   For now, we’ll leave the “Advanced Configurations” settings at the bottom of the page untouched.

5. In Github, navigate to the webhook settings on one of your repos.

   1. Log in to Github.

   2. Navigate to one of your repos.

   3. Go to the “Settings” in that repo.

   4. Once in settings navigate to “Webhooks” and click “Add webhook”.

      

      

      

      

      
      

6. Fill in the fields:

   1. Payload URL: Paste the Webhook URL from Moveworks

   2. Content type: application/json

   3. Secret: Keep blank for now

   4. SSL verification: Enable SSL verification

      

      
      

7. Under "Which events would you like to trigger this webhook?" select: Let me select individual events. Check ✅ Issues.

   1. Note: This means that the webhook will only fire on when events related to “issues” on your repo occur. Not all apps support this type of filtering natively but many do. If an app doesn’t support this natively, we do in listener configuration settings “Event Filtering”.

      

      
      

8. Finally, click “Add webhook” and you’re done on the Github side for now.

   

   
   

9. Everything should be set up correctly but let’s confirm that things are working! For now, let’s do that directly in Github.

   1. When you first set up your webhook, GitHub will send out a test payload to your webhook listener. Not all webhook providers do this, but many do.

      

      
      

   2. Navigate back to the webhook you just set up. Then go to the “Recent Deliveries” tab. You should see at least one entry here. Click on it. If it was successful you’ll see a 200 Response code and Headers and a Payload below. This confirms that the webhook was sent and received.

   3. You’ve now set up webhook in Moveworks which listens issues opened, edited, deleted, etc. in your Github repo! 🙌

Phase 2: Create Your Compound Action

1. In Agent Studio, navigate to “Compound Action” in the left nav and then click “Create”.

   

   
   

2. Give your compound action a Name and Description. Suggestion:

3. Copy the following into the “Compound Action Editor” and swap out [email protected] for your email.

   YAML

   steps:
     - action:
         action_name: mw.get_user_by_email
         input_args:
           user_email: '"[email protected]"'  # hardcoded for now
         output_key: mw_get_user_by_email_result
   
     - action:
         action_name: mw.send_plaintext_chat_notification
         input_args:
           message:
             RENDER():
               template: >-
                 New GitHub issue from @{{ sort of.user }}: "{{ data.title }}" {{ data.url }}
           user_record_id: data.mw_get_user_by_email_result.user.id
         output_key: notification_result
   

   1. Note: We’re hardcoding the email for now to keep things simple. In a real-world use case, you could make this dynamic based on the user who submitted the GitHub issue, or route it to a specific team.

      1. Add three input args into the compound action. Note: These input arguments define what data your compound action expects from the webhook payload. They must exactly match the keys defined in the input mapper (title, url, and user) on trigger (which you will define in the next step) otherwise your plugin won’t work.

         Argument Name	Data Type	Description	Required
         user	string	user field	yes
         title	string	title field	yes
         url	string	url field	yes

         

         
         

4. Click “Validate”. Fix any errors that arise then click “Publish”.

Phase 3: Configure Your Plugin

1. In Agent Studio, navigate to Plugins then click “Create”.

   

   
   

2. Again provide a Name and a Description. Suggestion:

   1. Name: yourmwid_Notify_GitHub_Issue
   2. Description: Sends a notification when a new GitHub issue is opened.

3. In the “Workflow Overview” section click “System” in the Trigger box.

   

   
   

4. Then Configure your System Trigger.

   1. Select Type: Webhook Trigger

   2. Select Listener: Select the listener you created in Step 1 for example: yourmwid_GitHub_Issue_Trigger_Test

   3. Event Filter: FALSE

   4. Input Mapping:

      1. title: parsed_body.issue.title
      2. url: parsed_body.issue.html_url
      3. user: parsed_body.issue.user.login

      

      
      
      

      👉

      How did we arrive at the input mapping above?

      Note: When we support the “Auto Configure” functionality in the listener creation setup, this process will get easier but for now it is somewhat manual.

      1. First, I triggered the webhook in Github by creating an issue so I could see what the payload looked like.

         1. Go back to Github and the specific repo you configured the webhook for in Step 1. Then click on the “Issues”. Then click “New Issue”.

         2. Name your new bug whatever you’d like and click “Create”.

      2. Now let’s go look at the payload for this new issue event.

         1. In your repo go back to “Settings” then “Webhooks”

         2. Select the wehook you created in Step 1 an click on the “Recent Deliveries” tab

         3. From there click on the most recent event you generate and look at the payload

         4. The fields we care about for our plugin are as follows:

            1. issue.title
            2. issue.html_url
            3. issue.user.login

         5. Why parsed body?

            1. We want to use the parsed body when there is JSON payload. You also have access to the headers and the query params.

5. Then click on the Body box to configure.

   1. Select Type should be “System Body”
   2. And select the name of the compound action you created in Step 2 — yourmwid_Notify_GitHub_Issue.

6. Finally, navigate to the “Launch Configuration” tab. Select “Allow selected users” and add in your own email.

   

   
   

7. Click “Validate”. Fix any errors that arise then click “Publish”.

8. You plugin has been created! Now we’re ready to test.

Phase 4: Testing

To test this out we need to create an issue and trigger an event in Github.

1. Go back to Github and the specific repo you configured the webhook for in Step 1. Then click on the “Issues”. Then click “New Issue”.

   

   

   
   

2. Name your new bug whatever you’d like and click “Create”.

   

   
   

3. If all is working well your plugin should execute and your should get an notification in MoveDev that look like this:

   

   
   

4. Yay! You’ve successfully created your first webhook-triggered plugin 🙌