Webhooks

Habitica provides "webhooks" for certain actions that can occur in your account (for example, when you complete a task or when someone posts a message in a Guild that you belong to). A webhook will be triggered when such actions occur and it will send information about the action to a script or other tool on another website.

Technical Details[]

Habitica will call the webhook URL with a POST request.

You can specify which scripts should receive information from Habitica's webhooks by logging in to Habitica's website and going to User Icon > Settings > API.

More information is available in the Webhooks section of Habitica's API Documentation.

Specifying an incorrect URL can cause errors or slowness in Habitica so it's best to not use this feature if you are unsure how webhooks work. The webhook has 30 seconds to respond with a 2xx HTTP code before a timeout error gets triggered. The best practice is to respond to the Habitica server as soon as you receive a request with a 200 HTTP code and a non-empty response (e.g. very small json, or using HtmlService.createHtmlOutput()). This ensures that the Habitica server will stay connected to your webhook the minimum time necessary (you can process the data after having sent a response) and that you won't risk hitting the 30s timeout limit. A webhook that failed for more than 10 times in a month will be disabled automatically.

If you need help with developing a script that responds to a webhook, ask for advice from other developers in the Aspiring Comrades guild.

If you wish to gain recognition for your webhook development, please see Guidance for Comrades for more information.

Examples[]

Python Flask Example[]

The following script uses Python Flask to implement handling for webhooks. The URL that you enter into Habitica's website should look like: http://<your_ip>:<your_port>/taskevent

Flask listens on port 5000 by default, but you can specify a different port where indicated by <your_port>

If your script is hosted behind a firewall you may need to use port forwarding or allow access to the port through the firewall.

from flask import Flask, request
app = Flask(__name__)
  # URI for receiving inbound webhook request
@app.route('/taskevent', methods=['POST'])
def webhook():
    # Request contains data as shown at https://habitica.com/apidoc/#api-Webhook
     # .json converts request to Python dictionary
    print(request.json)  # type: dict
 
    # <YOUR CODE FOR HANDLING EVENT HERE>
 
    return '', 200 # Return 200 code to the sending webserver
 
if __name__ == "__main__":
    app.run(host='0.0.0.0', port='<your_port>')

Google Apps Script Example[]

The following script uses Google Apps Script to listen to Habitica Webhooks. The script has to be saved as a new version upon every edit using "Manage Versions". To take effect the new version has to be deployed as a "Web App", running the script "As Yourself" and granting access to "everyone, even anonymous".

Following example will instantly auto-accept a quest invitation:

// [Users] Required script data to fill in
const USER_ID = "PasteYourUserIdHere";
const API_TOKEN = "PasteYourApiTokenHere"; // Do not share this to anyone

// [Users] Do not edit code below this line

// [Developers] If you're authoring your own script, place your user ID and
//   script name here. If just using this as a sample, you can leave as is.
const AUTHOR_ID = "01daa187-ff5e-46aa-ac3f-d4c529a8c012";
const SCRIPT_NAME = "Faster Auto Accept Quests";
const HEADERS = {
  "x-client" : AUTHOR_ID + "-" + SCRIPT_NAME,
  "x-api-user" : USER_ID,
  "x-api-key" : API_TOKEN,
}

// [Developers] This is the function that will be executed whenever Habitica
//   encounters the event designated by the webhook
function doPost(e) {
  var dataContents = JSON.parse(e.postData.contents);
  var type = dataContents.type;

  if (type == "questInvited") {
    api_acceptQuest();
  }

  return HtmlService.createHtmlOutput();
}

function api_acceptQuest() {
  var params = {
    "method" : "post", 
    "headers" : HEADERS,
    "muteHttpExceptions" : true,
  }

  var url = "https://habitica.com/api/v3/groups/party/quests/accept";
  UrlFetchApp.fetch(url, params);
}

Some detail: Webhook processing with Google Apps Script

Third-Party Tools for Webhooks[]

Currently, Habitica's own interface for creating and editing webhooks is limited, however Habitica's API provides more control, which means that third-party tools can be used to help you set up webhooks, such as the one listed below. The Extensions, Add-Ons, and Customizations page may list others. As with any third-party tool, you should carefully assess whether they are suitable for you to use. Habitica's staff do not support the tools directly or vouch for them.