A webhook is a callback mechanism that allows you to instantly respond to the appearance of a task at a certain step.

To get started, you must do the following:

1. Develop a web service that will handle Pyrus requests, and upload it to your server or the cloud.
2. Create a bot and specify the URL for the event handler.
3. Add the bot to the form wokflow at the appropriate step.

When a task is delivered to a bot’s Inbox, Pyrus sends the HTTPS POST request to the event handler. Your bot must respond to the request with the 2XX status within 60 seconds of this call. If you need to add a comment to the task, you can write it into the response body. The response body has the same structure as the POST /tasks/{task-id}/comments.

Example request:

{
  event: "comment",
  access_token: "Dfpb1we4..."
  task_id: 1532,
  user_id: 1725,
  "task": {
    "text": "Budget approval",
    "id": 11611,
    "create_date": "2017-08-17T15:32:11Z",
    "last_modified_date": "2017-08-17T15:32:11Z",
    "author": {
      "id": 1731,
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "Bob.Smith@gmail.com"
    },
    "responsible": {
      "id": 1245,
      "first_name": "my bot",
      "last_name": "",
      "email": bot@4e83a7da-3ba1-4a16-a1d8-21bbd1ad9592
    },
    "participants": [
      {
        "id": 1245,
        "first_name": "my bot",
        "last_name": "",
        "email": bot@4e83a7da-3ba1-4a16-a1d8-21bbd1ad9592
      },
      {
        "id": 1731,
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "Bob.Smith@gmail.com"
      }
    ],
    "comments": [
      {
        "id": 13767,
        "create_date": "2017-08-17T15:32:11Z",
        "text": "Budget approval",
        "author": {
          "id": 1731,
          "first_name": "Bob",
          "last_name": "Smith",
          "email": "Bob.Smith@gmail.com"
        },
        "reassigned_to": {
          "id": 1245,
          "first_name": "my bot",
          "last_name": "",
          "email": bot@4e83a7da-3ba1-4a16-a1d8-21bbd1ad9592
        },
        "participants_added": [
          {
            "id": 1245,
            "first_name": "my bot",
            "last_name": "",
            "email": bot@4e83a7da-3ba1-4a16-a1d8-21bbd1ad9592
          },
          {
            "id": 1731,
            "first_name": "Bob",
            "last_name": "Smith",
            "email": "Bob.Smith@gmail.com"
          }
        ]
      }
    ]
  }
}

If the bot server is unavailable or responds with a status other than 2xx, Pyrus sends a second request in 61 seconds and a third one in 122 seconds. You can see the number of attempts in X-Pyrus-Retry, the additional header of the request. If Pyrus fails to communicate within three attempts, it will stop trying to call the bot until someone comments on the task.

Request headers:

• User-Agent. The value is Pyrus-Bot-4. In this case, 4 stands for the protocol version (the same as Pyrus API version).
• X-Pyrus-Sig. This value is a string with a signature confirming that the request actually came from Pyrus. To verify this signature, add your Security Key to the request body and compile an HMAC digest for the resulting string with the SHA1 secure hash algorithm. Here's an example of signature verification in Python.
• X-Pyrus-Retry. The value is either 1/3, or 2/3, or 3/3. The numerator is the attempt count (starting with 1), the denominator is the total number of attempts available (3). For the first non-repeat request, the value would be 1/3.

• Create a Pyrus bot on the bots page (if you already have one to access the Pyrus API, you can use it).
• Clone the initial bot application from github and go to its folder:

git clone https://github.com/simplygoodsoftware/heroku-python-bot.git
cd heroku-python-bot

• Specify the bot's security key in the config file config.json

{
  "SECRET_KEY": "Bot-Secret-Key"
}

• Create and run a Heroku application:

heroku create
git add .
git commit -m "replaced SECRET_KEY in config.json"
git push heroku master
heroku ps:scale web=1

• Specify the URL received on the previous step in the Pyrus bot settings.
• Create a task in Pyrus and assign it to the bot. You should see a comment with the bot's response:

Hello, {user_name}! You said "{comment_text}".