Until now, your interactions with Webex APIs 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 pre-configured URL to notify your application that a specific event has occurred. Although we are going to explore webhooks in the context of Messaging APIs, webhooks can be used for other purposes like receiving events from Webex about Meetings or Calling.

A webhook involves the Webex Cloud initiating an outbound HTTPS request to your applicaiton. 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 on the Internet that forwards requests to your internal application in order to safeguard your internal servers. 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

If a bot has been configured with a webhook to receive notifications when a message it sent to the bot, Webex sends a webhook notification immediately upon receiving that message, but what does the webhook actually look like? To illustrate this, we have a pre-configured 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 through the Webex App, Webex sends a webhook message as an HTTP POST to the Bot's configured webhook URL. The bot is configured to read the contents of that webhook notification and just echo it back to the person that sent it.

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 helpful 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: pod5wbxuser@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. Also, when you subscribe to a webhook, you can subscribe to specific resources and/or events that you are interested in. This example is a messages created event, but there are many others across different workloads in Webex.
   

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 you cannot 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 pod5wbxuser@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/messaging/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

Now that you have explored the data that is sent to a webhook, you can create a webhook for your Bot to receive these messages. Follow the steps below to create a webhook for your Bot.

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/messaging/docs/api/v1/webhooks/create-a-webhook
2. On the right, you will see the request body as an HTML form, explaining all the parameters. To register a webhook, you only need the mandatory event, name, resource, and targetUrl fields specified. One of the limitations of this Request Body (Form) view is that all fields (even non-mandatory ones) are shown and include sample data. Since you do not want to send those fields at all, switch to the Request Body (JSON) view by clicking on its tab.
   

3. Now you can see the raw body that will be sent. As mentioned, you will require the following fields and values:

   Parameter	Value	Description
   event	created	This is a kind of event action. created means any new Message or Attachment Action
   name	Cisco Live LTRCOL-2574 Webhook	Not visible, so only useful for admins to determine the use of a certain webhook
   resource	messages	Describes the 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 different kinds of events you must create a webhook for each event type.
   targetUrl	http://collab-api-webhook.ciscolive.com:9005/api/v1/wbxt/events	The "callback" location where Webex will POST webhook events to

   To simplify entering this, you can paste the following into the Request Body (JSON) window, overwriting the previous contents:

4. That takes care of the body of the request, but you still need to include an authorization token. In this case, the request needs to be performed by the bot, so you will need to use the Bot's access token. Retrieve 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. Scroll down to the Headers section and find the Authorization header line and replace <YOUR_AUTHORIZATION_TOKEN> (but leaving the "Bearer " part of the line) with your Bot's token.
   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.

5. Click Run at the bottom.
   

6. Since it is not possible to register a webhook for more than one resource at a time, repeat this API call 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). The following is the exact same JSON as before, but with the resource changed to attachmentActions. Scroll up to the Request Body (JSON) and paste it over the previous data:

7. 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. The next section will expand on this knowledge through a provisioning web portal example, covering error handling and Python interactions with webhook messages.