Help center

API webhooks

Here you can read AssistBot webhooks documentation.

Description

The AssistBot uses webhooks to notify your applications when some event happens in your AssistBot account. You can listen for webhooks by doing these steps:

  1. Create an endpoint on your server. It must be HTTPS address with valid SSL certificate. You can also implement verification methods to make sure webhooks originate from AssistBot;
  2. Open company settings in AssistBot and set endpoint URL. Do this step after creating and testing your endpoint;
  3. Test webhooks.

Webhooks payloads are JSON objects with data of triggered event.

You must send 200 OK response to the each webhook. AssistBot will not retry sending webhook in case of error on your endpoint.

Please note that not all events in AssistBot triggers webhooks. All supported events listed below on this page.

Webhook headers

  • X-Generated-By

    Contains name of the AssistBot service.

  • X-AssistBot-Path

    Contains path for easy identification of current webhook type.

  • X-AssistBot-Key

    Contains HMAC SHA-256 key for verifying current webhook.

  • Content-Type

    Content type of the current webhook.

WEBHOOK HEADERS SAMPLE 
X-Generated-By: AssistBot,
X-AssistBot-Path: poll/vote,
X-AssistBot-Key: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ,
Content-Type: application/json

Webhook verification

You can optionally verify all webhooks sent from AssistBot to make sure that they actually originate to AssistBot.

Needed parameters

  • API key

    Use your API key which you can take from company settings in AssistBot admin panel.

  • Webhook payload

    Current webhook's payload whole object without headers. You must convert payload to JSON if this not yet converted.

  • Webhook X-AssistBot-Key header

    The X-AssistBot-Key header from the current webhook.

VERIFICATION EXAMPLE
Node.js 
const crypto = require('crypto');
const key = 'Your API key';

function VerifyWebhook(payload, headers) {
   let json = JSON.stringify(payload);
   let hmac = crypto.createHmac('sha256', key).update(json).digest('base64');
   return hmac === headers['X-AssistBot-Key'];
}

VerifyWebhook(req.body, req.headers);

/*
const req = {
   headers: {
      'X-Generated-By': 'AssistBot',
      'X-AssistBot-Path': 'poll/vote',
      'X-AssistBot-Key': '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ',
      'Content-Type': 'application/json'
   },
   body: {
      id: 1,
      name: 'Vacation poll',
      description: 'Where do you spend your vacation?',
      app: 'tg',
      member: {
         id: 1,
         name: 'John Doe',
         nickname: '@john_doe_nickname',
         email: 'johndoe@company.com'
      }
   }
}
*/

Report sumbission

This type of webhook triggers when somebody from your company submitted full standup report. Payload contains information about submitted report.

Paths

  • report/submit

Payload attributes

  • id integer

    Report id.

  • name string

    Standup name.

  • dt integer

    UTC timestamp of report sumbitting.

  • app string

    Name of application from which member submitted report.

  • member object

    Object containing data about member who submitted the report.

  • member.id integer

    Member's id.

  • member.name string or null

    Member's name. NULL if name doesn't specified.

  • member.nickname string or null

    Member's nickname in the application from which he submitted the report. NULL if nickname doesn't exists.

  • member.email string

    Member's email.

  • report object

    Object containing report's data.

  • report[x].id integer

    Question id.

  • report[x].blocker boolean

    Is current question a blocker.

  • report[x].question string

    Question text.

  • report[x].response string

    Member's response to the question. If this question is blocker and member skipped it, response will be "no".

WEBHOOK PAYLOAD
JSON 
{
   id: 1,
   name: 'Daily question',
   dt: 1603967539,
   app: 'tg',
   member: {
      id: 1,
      name: 'John Doe',
      nickname: '@john_doe_nickname',
      email: 'johndoe@company.com'
   },
   report: [
      {
         id: 1,
         blocker: false,
         question: 'What did you do yesterday?',
         response: 'A lot of work'
      },
      {
         id: 2,
         blocker: true,
         question: 'Any blockers?',
         response: 'Probably'
      }
   ]
}

Task handling

This type of webhook triggers when somebody from your company completed or canceled a task item. Payload contains information about whole task.

Paths

  • task/complete

    Appears when member completed the task item.

  • task/cancel

    Appears when member canceled the task item.

  • task/restore

    Appears when member restored the task item.

Payload attributes

  • id integer

    Task id.

  • name string

    Task name

  • description string

    Task description.

  • app string

    Name of application from which member handled task.

  • member object

    Object containing data about member who handled the task.

  • member.id integer

    Member id

  • member.name string or null

    Member's name. NULL if name doesn't specified.

  • member.nickname string or null

    Member's nickname in the application from which he handled the task. NULL if nickname doesn't exists.

  • member.email string

    Member's email

  • task_items object

    Object containing data about task items.

  • task_items[x].id integer

    Task item id.

  • task_items[x].description string

    Task item description.

  • task_items[x].member_id integer

    Id of member in charge of this task item.

  • task_items[x].canceled boolean

    Is task item canceled.

  • task_items[x].deadline integer or null

    Is task item has deadline. NULL if doesn't has.

  • task_items[x].completed boolean

    Is task item completed.

  • task_items[x].dt integer or null

    UTC timestamp of task completion or cancelling. NULL if not completed or not canceled.

WEBHOOK PAYLOAD
JSON 
{
   id: 1,
   name: 'Complete the project',
   description: 'Complete the project and deploy it in public access.',
   app: 'tg',
   member: {
      id: 1,
      name: 'John Doe',
      nickname: '@john_doe_nickname',
      email: 'johndoe@company.com'
   },
   task_items: [
      {
         id: 1,
         description: 'Finish programming',
         member_id: 1,
         canceled: false,
         deadline: false,
         completed: true,
         dt: 1603968091
      },
      {
         id: 2,
         description: 'Deploy project',
         member_id: 1,
         canceled: false,
         deadline: false,
         completed: false,
         dt: null
      }
   ]
}

Polling

This type of webhook triggers when somebody from your company voted in a poll. Payload contains information about the poll. As voting in AssistBot is anonymous, we don't provide poll results in the payload.

Paths

  • poll/vote

Payload attributes

  • id integer

    Poll id.

  • name string

    Poll name.

  • description string

    Poll description.

  • app string

    Name of application from which member submitted the vote.

  • member object

    Object containing data about member who submitted the vote.

  • member.id integer

    Member id.

  • member.name string or null

    Member's name. NULL if name doesn't specified.

  • member.nickname string or null

    Member's nickname in the application from which he submitted the vote. NULL if nickname doesn't exists.

  • member.email string

    Member's email.

WEBHOOK PAYLOAD
JSON 
{
   id: 1,
   name: 'Vacation poll',
   description: 'Where do you spend your vacation?',
   app: 'tg',
   member: {
      id: 1,
      name: 'John Doe',
      nickname: '@john_doe_nickname',
      email: 'johndoe@company.com'
   }
}

Motivation assessing

This type of webhook triggers when somebody from your company assessed motivation. Payload contains information about the member. As motivation assessing in AssistBot is anonymous, we don't provide motivation results in the payload.

Paths

  • motivation/submit

Payload attributes

  • divisions_id array

    Array of divisions ids.

  • app string

    Name of application from which member assessed motivation.

  • member object

    Object containing data about member who assessed motivation.

  • member.id integer

    Member id.

  • member.name string or null

    Member's name.

  • member.nickname string or null

    Member's nickname in the application from which he assessed motivation. NULL if nickname doesn't exists.

  • member.email string

    Member's email.

WEBHOOK PAYLOAD
JSON 
{
   divisions_id: [ 1 ],
   app: 'tg',
   member: {
      id: 1,
      name: 'John Doe',
      nickname: '@john_doe_nickname',
      email: 'johndoe@company.com'
   }
}