There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. Your API Keys could be deactivated at any time after Nov. 30th, and we recommend that you migrate to Private Apps as soon as possible so you do not lose business-critical functionality.

Working with webhooks from bots

When creating or editing a bot, you may add a webhook by clicking the "+" to add an action as you normally would. From the action selection panel, click on "Trigger a webhook"trigger-a-webhook 

Next, give your action a nickname and input the endpoint URL for the webhook.  If your webhook will be sending data to HubSpot in response to the request, you may check the "Wait for webhook feedback" box. (Read more on this below)trigger-a-webhook-editor

Once you've saved your action, the webhook will be triggered once the applicable part of the conversation has been reached.

When we trigger a webhook, we pass a payload that contains relevant information to the chat session - including the visitors' responses to any questions asked, their contact ID and information about the bot.

Example request payload:

  "userMessage": {
  // Details for the last message sent to your bot
    "message": "100-500",
    // The last message received by your bot, sent by the visitor
    "quickReply": {
    // If the visitor selected any quick reply options, this will be a list of the selected options.
    // Will be 'null' if no options were selected.
      // A list of quick reply options selected by the visitor
  "session": {
    "vid": 12345,
    // The contact VID of the visitor, if known.
    "properties": {
    // A list of properties collected by the bot in the current session.
      "CONTACT": {
        "firstname": {
          "value": "John",
          "syncedAt": 1534362540592
        "email": {
          "value": "",
          "syncedAt": 1534362541764
        "lastname": {
          "value": "Smith",
          "syncedAt": 1534362540592

For advanced users, you may also optionally include JSON in your webhook's response that will impact the flow of conversation. By doing this, you may impact the flow of conversation or send a custom message based on your webhook's response.

Example response payload:

  "botMessage": null,
   // This is the message your bot will display to the visitor.
  "nextModuleNickname": "PromptForCollectUserInput",
   // If defined, this will be the next module your bot will go to. If undefined, the default configured behavior will be observed.
  "responseExpected": false
  // If true, the webhook will be triggered again with the visitor's next reply. If false, the default configured behavior will be observed.