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[edit | edit source]

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[edit | edit source]

  1. Go to https://script.google.com
    • If this is your first time on this website, click on “Start Scripting”
      Button StartScripting.png
    • 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”
    Button NewProject.png
    • 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”
    Screenshot SelectAll.png
  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”
    Screenshot UserId.png
  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.
      Screenshot PasteYourUserIdHere.png
  16. Paste the user ID that you copied from the previous steps
    • Note that the quotation marks should still be there
      Screenshot PastedUserId.png
  17. Go back to https://habitica.com/user/settings/api​​​
  18. Click on “Show API Token”
    Screenshot ShowApiToken.png
    • This will show a second set of numbers and letters
      Screenshot ApiToken.png
  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:
      Screenshot ApiTokenWarning.png
  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.
      Screenshot PasteYourApiTokenHere.png
  21. Paste the API token that you copied from the previous steps
    • Note that the quotation marks should still be there
      Screenshot PastedApiToken.png
  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”
    Screenshot Save.png
  25. When asked for the project name, just enter the name of the script from the scripts page, then click “OK”
    Screenshot EditProjectName.png
  26. Click on “Publish”, then “Deploy as web app...”
    Screenshot DeployAsWebApp.png
  27. Under “Project version:”, type “Added script”
    Screenshot ProjectVersion.png
  28. Under “Execute the app as:”, make sure it says “Me”
    Screenshot ExecuteTheAppAs.png
  29. Under “Who has access to the app:”, make sure it says “Anyone, even anonymous”
    Screenshot WhoHasAccessToTheApp.png
  30. Click “Deploy”
    Button Deploy.png
    ​​​​​​
  31. If the following message is displayed, click on “Review Permissions”
    Screenshot AuthorizationsRequired.png
    • A new window will open
  32. Choose the Google account you used in step 1
    Screenshot ChooseAnAccount.png
  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
      Screenshot ThisAppIsntVerified.png
  34. On the lower right, click “Allow”
    Screenshot WantsToAccessYourGoogleAccount.png
  35. Click “OK”
    Screenshot DeployAsAWebApp.png

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

Part 2. Set Up Habitica Webhook[edit | edit source]

  1. Click on “Publish”, then “Deploy as web app...”
    Screenshot DeployAsWebApp.png
  2. Select the complete URL under “Current web app URL:”, then copy
    Screenshot DeployAsWebAppCopy.png
  3. Click “Cancel”
    Button Cancel.png
  4. On line number 6, select PasteGeneratedWebAppUrlHere​​​​​​
    • Don’t select the quotation marks. This will make sure they are not overwritten when you paste.
      Screenshot PasteGeneratedWebAppUrlHere.png
  5. Paste the URL copied from the previous steps
    • Note that the quotation marks should still be there
      Screenshot PastedWebAppUrl.png
  6. Click on “Run”, then “Run function”, then “doOneTimeSetup”
    Screenshot doOneTimeSetup.png
    • ​​​A yellow message will momentarily pop up on the top of your screen, no need to click anything
      Screenshot RunningDoOneTimeSetup.png
    • 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.

YouTube step by step instructions (Setting auto-accept quests on this example)


Setting Up Traditional Scripts[edit | edit source]

Part 1. Set Up External Script[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

  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[edit | edit source]

  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[edit | edit source]

  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.

Community content is available under CC-BY-SA unless otherwise noted.