Event-Driven (Webhook) Scripts Setup Guide

Event-driven (webhook) scripts require more steps to set up than either manually-driven scripts or time-driven scripts. The user needs to set up two things, in this order:

1. First, the external script that will process the automatic request sent by Habitica.
2. Second, the trigger on Habitica that will cause it to send an automatic request whenever the designated event happens. This is called the "webhook".

This guide will give step by step instructions to doing both parts.

Setting Up Streamlined Scripts

Streamlined scripts are scripts that use the streamlined event-driven script template. These scripts allow the user to set up event-driven scripts with fewer number of steps and without going back and forth between different tools.

Video instructions:

If you prefer to watch the instructions rather than read them, see these YouTube videos below. If you'd rather read the instructions (with pictures!), you can find them immediately below the videos.

• Video only, no audio: example for setting up auto-accept quests
• Video with audio explanation (English): example for setting up Bad Day Mode script

Written instructions with pictures:

Part 1. Set Up External Script

1. Go to https://script.google.com
   • If this is your first time on this website, click on “Start Scripting”

     
   • If you are prompted with a Google sign in page, enter your Gmail address and password if asked
2. On the upper left part of the screen, click on “New Project”

   

   • This will open a new tab with your new project
3. Your cursor will be on line 2 of the myFunction sample function. Select all the text by pressing “CTRL + A” (PC) or “command + A” (Mac).

   
4. Delete the entire myFunction sample function
   • The script should now be completely blank
5. Click on the name of the script you want to set up from the list of Streamlined Event-Driven Scripts
6. On the section that says "Code", click on the link
   • A new tab will open with the code
7. Copy all the text on the new tab that opened from the previous step
8. Go back to the tab with your blank project (the tab previously created from step 2), then paste this copied text
9. Go to https://habitica.com/user/settings/api
10. On the left part of the screen, look for your “User ID”

    
11. Copy that entire string of numbers and letters
    • Including the dashes, just copy the whole thing
12. On the tab with your new script, on the line marked const USER_ID = , select all text inside the quotation marks

    
13. Paste the user ID that you copied from the previous steps
    • Note that the quotation marks should still be there

      
14. Go back to https://habitica.com/user/settings/api
15. Click on “Show API Token”

    

    • This will show a second set of numbers and letters

      
16. Copy that entire string of numbers, letters, and dashes
    • Note: Do not ever show/share this API token to anybody, see warning below:

      
17. On the tab with your new script, on the line marked const API_TOKEN = , select all text inside the quotation marks

    
18. Paste the API token that you copied from the previous steps
    • Note that the quotation marks should still be there

      
19. If the section called "Required Customizations" exist on the script's description on the scripts page, check through the items listed on this section and modify the indicated values
20. [Optional] If the section called "Optional Customizations" exist on the script's description, check through the items listed on this section and modify the indicated values
21. Click on “Untitled project” at the top of the screen

    
22. Enter the name of the script from the scripts page, then click “Rename”

    
23. Click on the "Save" icon on the toolbar

    
24. Click the “Deploy” button, then “New deployment”

    
25. Click on the “Settings” icon (gear), then click on “Web app”

    
26. Under "New description" type something brief that will help you identify what was changed, such as "Added script"

    
27. Under “Execute as:”, make sure it says “Me”

    
28. Under “Who has access”, make sure it says “Anyone”

    
29. Click “Deploy”

    
30. If the following message is displayed, click on “Authorize access”

    

    • A new window will open
31. Choose the Google account you used in step 1

    
32. On the lower left, click “Advanced”, then click “Go to <name of script> (unsafe)”
    • The app being mentioned here that isn’t verified is the new project you made

      
33. On the lower right, click “Allow”

    
34. Under "Web app" click "Copy"

    
35. Click “Done”

    
36. On the appropriate line for const WEB_APP_URL = , select all the text inside the quotation marks

    
37. Paste the URL copied from the previous steps
    • Note that the quotation marks should still be there

      

38. Ensure the toolbar dropdown has “doOneTimeSetup” selected

    
39. Click “run”

    

    • The “Execution log” will open on the bottom of your screen and will show “Execution completed” when the one-time setup is successful

      
    • If "doOneTimeSetup" is not on the choices, or if an error message is shown, it could mean that one of the previous steps was not done properly. Please repeat the steps starting from Part 1. Set Up External Script
40. [Optional] Go to https://habitica.com/ and click on the Sync button in case the script creates reward task buttons

If you see "Execution completed" in the Execution Log on step 39 with no error message shown, you’ve successfully completed all the steps! Enjoy your new script!

If you have any questions or concerns regarding unexpected behavior encountered while setting up or using scripts, please go to the scripts troubleshooting page.

Part 2. Set Up Habitica Webhook

Note: This process is integrated into Part 1: Set Up External Script above. The below steps outline how to set up a webhook for an existing script.

1. Go to https://script.google.com
2. Open the desired script by clicking on it
3. Click the “Deploy” button, then “Manage deployment”

   
4. Go to the appropriate Active deployment (the most recent will be on top)

   
5. Under "Web app" click "Copy"

   
6. Click “Cancel”

   
7. On the appropriate line, select PasteGeneratedWebAppUrlHere
   • Don’t select the quotation marks. This will make sure they are not overwritten when you paste

     
8. Paste the URL copied from the previous steps
   • Note that the quotation marks should still be there

     

9. Click on the "Save" icon on the toolbar

   
10. Ensure the toolbar dropdown has “doOneTimeSetup” selected

    
11. Click “run”

    

    • The “Execution log” will open on the bottom of your screen and will show “Execution completed” when the one-time setup is successful

      
    • If "doOneTimeSetup" is not on the choices, or if an error message is shown, it could mean that one of the previous steps was not done properly. Please repeat the steps starting from Part 1. Set Up External Script
12. [Optional] Go to https://habitica.com/ and click on the Sync button in case the script creates reward task buttons

If you see "Execution completed" in the Execution Log on step 11 with no error message shown, you’ve successfully completed all the steps!

If you have any questions or concerns regarding unexpected behavior encountered while setting up or using scripts, please go to the scripts troubleshooting page.

Setting Up Traditional Scripts

Part 1. Set Up External Script

Setting up the external script for traditional scripts is similar to the steps for streamlined scripts. The only difference is that the lines where you need to put your user ID, API token, and any other user-defined customizations may look a little bit different. Reading the the script's accompanying documentation will help.

Part 2. Set Up Habitica Webhook

Traditionally, to set up a webhook, you need to learn how to use some third-party tools and set up the webhook manually using these tools.

Applying Updates to Streamlined Scripts

There are times when an author updates their script, either to fix some problems or to add new features. The sections below show the three parts that possibly need to be done to apply these updates on your deployment of the script. For each particular script update, the author of the script will indicate which part among these three parts below are necessary to apply that specific update.

Part 1. Delete Items Created by doOneTimeSetup

1. Go to https://script.google.com and open the script you want to update
2. Take note of the URL on line 6
3. Go to https://habitica.com/user/settings/api
4. On the right side, under Webhooks, look for all the lines with the same URL as the one on step 2 above
   • You may need to press the right arrow key on your keyboard several times to see the entire URL
   • There could be more than one line with this URL, for the case of scripts which use more than one webhook
5. Click "Delete" on all those lines with matching URL
   • Note: There will never be a need for you to manually add a URL here in later steps
6. Go to https://habitica.com
7. If the script created some reward buttons before when you were initially setting it up, delete all of these created reward buttons

Part 2. Update External Script

1. Click on the name of the script you want to update from the list of Streamlined Event-Driven Scripts
2. On the section that says "Code", click on the link
   • A new tab will open with the code
3. Copy all the text below the line that says /* [Users] Required customizations to fill in */
4. Go to https://script.google.com and open the script you want to update
5. Delete all the text below the line that says /* [Users] Required customizations to fill in */
6. Paste the text copied from step 3
7. Only if lines 4-6 have "habiticaUserId", "habiticaApiToken", and "webAppUrl", replace them with "USER_ID", "API_TOKEN", and "WEB_APP_URL" respectively.
8. If the section called "Required Customizations" exist on the script's description on the scripts page, check through the items listed on this section and modify the indicated values
9. [Optional] If the section called "Optional Customizations" exist on the script's description, check through the items listed on this section and modify the indicated values
10. Click on “File”, then “Save”
11. Click on “Publish”, then “Deploy as web app...”
12. Under “Project version:”, type “Updated script”
13. Click “Update”
14. If the "Authorization required" message is displayed, click on “Review Permissions”
    • If the "Authorization required" message is not displayed, just go directly to step 16
15. Choose the Google account you used when you initially set up the script
16. On the lower left, click “Advanced”, then click “Go to <name of script> (unsafe)”
17. On the lower right, click “Allow”
18. Click “OK”

Part 3. Recreate Items Created by doOneTimeSetup

1. Click on “Run”, then “Run function”, then “doOneTimeSetup”
   • A yellow message will momentarily pop up on the top of your screen, no need to click anything
2. [Optional] Go to https://habitica.com/ and click on the Sync button in case the script creates reward task buttons

If you have completed the steps in all the parts indicated by the script's author, you have successfully updated the script.

If you have any questions or concerns regarding unexpected behavior encountered while setting up or using scripts, please go to the scripts troubleshooting page.