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.

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. On the far right, click "Use legacy editor"
4. Close the popup window named "Editor Opt-out Survey"
5. If the message, "Try the brand new Apps Script editor" is displayed, click "Don't ask me again"
6. Click on “Edit”, then “Select all”

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

    
14. Copy that entire string of numbers and letters
    • Including the dashes, just copy the whole thing
15. On the tab with your new script, on line number 4, select PasteYourUserIdHere
    • Don’t select the quotation marks. This will make sure they are not overwritten when you paste.

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

      
17. Go back to https://habitica.com/user/settings/api​​​
18. Click on “Show API Token”

    

    • This will show a second set of numbers and letters

      
19. Copy that entire string of numbers and letters
    • Including the dashes, just copy the whole thing
    • Note: Do not ever show/share this API token to anybody, see warning below:

      
20. On the tab with your new script, on line number 5, select PasteYourApiTokenHere
    • Don’t select the quotation marks. This will make sure they are not overwritten when you paste.

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

      
22. 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
23. [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
24. Click on “File”, then “Save”

    
25. When asked for the project name, just enter the name of the script from the scripts page, then click “OK”

    
26. Click on “Publish”, then “Deploy as web app...”

    
27. Under “Project version:”, type “Added script”

    
28. Under “Execute the app as:”, make sure it says “Me”

    
29. Under “Who has access to the app:”, make sure it says “Anyone, even anonymous”

    
30. Click “Deploy”

    

    ​​​​​​
31. If the following message is displayed, click on “Review Permissions”

    

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

    
33. 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

      
34. On the lower right, click “Allow”

    
35. Click “OK”

    

The first part is now done. Part 2 below is shorter and also needs to be performed.

Part 2. Set Up Habitica Webhook

1. Click on “Publish”, then “Deploy as web app...”

   
2. Select the complete URL under “Current web app URL:”, then copy

   
3. Click “Cancel”

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

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

     
6. 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

     
   • If either "doOneTimeSetup" is not on the choices, or a red 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
7. [Optional] Go to https://habitica.com/ and click on the Sync button in case the script creates reward task buttons

If the yellow message on step 6 simply disappears with no red 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.

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.