Until now, your interactions with Webex have involved sending instructions to Webex to perform actions, and receiving success or failure responses. What if you want your application to be notified when a specific event occurs within Webex, such as a message being sent to your bot? Webex utilizes webhooks for this purpose. A webhook is a mechanism for Webex to initiate an HTTP/HTTPS message to a preconfigured URL to notify your application that a specific event has occurred.

Since this traffic is initiated from the Internet (i.e. Webex Cloud), the additional security exposure must be considered. In most cases, a reverse proxy (such as nginx) is deployed in order to safeguard your internal servers. The idea is that when Webex sends a message to this reverse proxy, the proxy decides if the request can be trusted and forwards it to an internal server, and that server's reply is sent back via the proxy. Webex also provides some shared secrets in the messages as an additional layer of protection to allow your application to authenticate that the requests were legitimately received from Webex.

In this lab, the reverse proxy portion won't be covered in detail, however you will have the ability to receive events from Webex, which you will need to process. Let's see what this looks like. In this section, you will examine the following key aspects:

1. Webhook Message Events
2. Adaptive Cards
3. Register a Webhook for the Bot

Step 1 - Webhook Message Events

You know how to send a message via Webex, but what does the data look like, if that triggers a webhook? To illustrate this, we have a preconfigured Bot and web server that simply echos back the webhook data that it receives. This diagram shows how this Bot works. When you send a message to this Bot, Webex POSTs a webhook message to the Bot's webhook URL. Once that web server receives the webhook data, it sends the received payload directly back to you.

In subsequent sections of this lab, you will configure your own web server to receive and process webhook events in Python. Before creating your own webhook, it is essential to understand the structure of the message sent from Webex to a webhook URL.

1. If necessary, launch your Webex app. Sign in using email: pod6wbxuser@collab-api.com and password: C1sco.123
2. Click to start a conversation with the Webhook Echo Bot (webhook-echo@webex.bot). When prompted by Chrome to Open Webex, click Open Webex and when Webex App asks if you want to create a space, say Yes.
   The source code for the Webex Webhook Echo Bot can be downloaded here. It is a simple example of a Bot that responds to both text and adaptive card interactions.

3. Type a message and press enter to send.
4. Inspect the response (or take a look at this sample response shown below). You will notice a few things:
   • the resource type is messages
   • the event is created
   • the data portion has various components, such as an id and roomId, but they are all just object IDs. The actual message or even the Space name is never transmitted as part of the webhook POST notification. This provides an additional layer of security by ensuring that your application must go back to Webex to retrieve the message.
   

5. At the bottom of the Bot reply, you also see some decoded values for the Room/Space name, the sender, and the message. But we do not see those values in the message payload itself. Take the message text for instance. To find its value, the Bot used the data id (which is a Message ID) to perform a query using Get Message Details from the Webex API documentation.
   
   If you take the id value in the data from the response and place it in the messageId field of the Get Message Details, while logged in as pod6wbxuser@collab-api.com (with password: C1sco.123 ), you should see the message as show below in the text field.
   

Step 2 - Adaptive Cards

Depending on your requirements, you can have a Bot that interacts with users purely using text-based messages. However, Webex also supports adaptive cards, which are a standard way to present a graphical response with features like buttons, check boxes, various input methods for text, numbers, and date/time elements. They are basically text-based content with JSON formatting that will be rendered by the Webex client as graphics and form items.

What this means is that the web server that handles webhook messages from Webex can reply with more than just text. It can also send an adaptive card, a form of JSON-formatted text, that the Webex client can use to display something graphical. It also means that when the user interacts with this interface, say they click a submit button, a different kind of webhook is triggered. Instead of a message, this will be an attachmentActions type of event. Therefore, on your web server, you may choose to send this kind of data and handle the events.

While this lab won't go into details on designing adaptive cards themselves, there are great resources from the Webex Adaptive Card Designer to the Microsoft Adaptive Card Designer (for the latter, make sure you select the correct Webex Adaptive Card version, currently 1.3). These tools provide a way to construct your card, and then simply copy out the JSON.

1. Click to resume your conversation with the Webhook Echo Bot (webhook-echo@webex.bot) in your Webex app.
2. For your message, paste the following JSON string:
   { "type": "AdaptiveCard", "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "version": "1.2", "body": [ { "type": "TextBlock", "text": "My Adaptive Card", "wrap": true, "id": "text_block" }, { "type": "Input.Text", "placeholder": "Enter text", "id": "input_text" }, { "type": "Input.Toggle", "title": "Checkbox", "id": "input_toggle", "value": "true" }, { "type": "ActionSet", "actions": [ { "type": "Action.Submit", "title": "Submit", "id": "submit_button" } ] } ], "id": "adaptive_card" }
3. Click Send
4. The Bot, in this case, is simply sending back the JSON string that you sent it. Your Webex app renders this exact content as an adaptive card.
   

5. Enter some text in the "Enter text" box and the card, then click Submit
6. You'll notice that in the response, the resource is attachmentActions That means that this time, under the data, the id is no longer referring to a Message ID, but rather an Attachment Action ID that can be retrieved via the API, similar to a message: https://developer.webex.com/docs/api/v1/attachment-actions/get-attachment-action-details The bot has done that for you and supplied the output below.
   

7. Retrieving the attachment allows you to get the data that was supplied via the card interaction. The input_text and input_toggle variables are defined in the card, but the general construct is always the same.
   

Step 3 - Register a Webhook

You've learned about some of the types of data that webhooks can supply, now you can finally configure the webhook itself.

1. Access the Create a Webhook link under the Webhooks API section in the Full API Reference of the Webex API documentation: https://developer.webex.com/docs/api/v1/webhooks/create-a-webhook
   If necessary, sign in with email address: pod6wbxuser@collab-api.com and password: C1sco.123
2. The most important part of this action is the Authorization header which determines on whose behalf we would like to configure a new webhook. Therefore, you must use your Bot's access token here. The goal is to have messages sent to your Bot via webhook notifications. Start by clicking on the button to disable the Use personal access token setting.
3. Now you will need your Bot's access token which you should have previously stored in the wbx_messages.py file in the examples directory as the variable wbx_bot_access_token. Paste it next to the Bearer field.
   If you don't have the Bot's access token, you can click on your user button in the top right then My Webex Apps. From there you can select your Bot and click Regenerate Access Token. This will invalidate the old token and create a new one. If you do this, be sure to go back and update the wbx_bot_access_token variable in wbx_messages.py.

4. Enter the following mandatory fields on the Create a Webhook page where you already pasted your Bot's access token:

   Parameter	Value	Description
   name	Cisco Live LTRCOL-2574 Webhook	Not visible, so only useful for admins to determine the use of a certain webhook
   targetUrl	http://collab-api-webhook.ciscolive.com:9006/api/v1/wbxt/events	The "callback" location where Webex will POST webhook events to
   resource	messages	Essentially a type of event, either messages or attachmentActions for adaptive cards actions, or a number of other events. Note that you can only ever supply one. To receive webhook notifications for differnet kinds of events you must create a webhook for each event type.
   event	created	This is a kind of event action. created means any new Message or Attachment Action

5. Click Run
   

6. Since it is not possible to register a webhook for more than one resource at a time, we will repeat this for the attachmentActions resource, which will be used when a user clicks on an adaptive card.
   Simply scroll up and paste attachmentActions in the resource line (overwriting the previous information in that row).
7. Everything else will stay exactly the same. Click Run.
   

You've learned about different API types in the Cisco Collaboration portfolio and how to build queries to achieve common tasks using both tools and in Python with the help of SDKs. If you choose to continue, the next section will expand on this knowledge through a provisioning web portal example, covering error handling and Python interactions with webhook messages.