Welcome back. So at this point, the baker at Ye Olde Bake Shoppe can notify VIP customers using a Communication Plan and can kick off this notification process with just an email. But using all these awesome tools has led to sooo many more customers that he can't make muffins fast enough! His solution is to have the customers reserve a muffin. And ideally he'd like to have that list of reservees displayed in his new BakeSoft application. BakeSoft v 0.0.1 is the latest bakery management application to hit the market.
Coincidentally, BakeSoft just happens to have a Muffin Reservation List available!
In this article, we're going to introduce responses to our notifications and then talk about webhooks. So let's get started. Our outgoing emails (and SMS and voice notifications!) don't have any way for the recipient to do anything, so our first task will be to add some a way for customers to take action. Crack open the xMatters UI and navigate over to the Developer tab and our Bakery Customers plan. In the edit drop down, you'll notice there is a "responses" entry.
Click that guy and you'll see a blank canvas, awaiting input.
Click the + Create Response button and a new response is added. This is chock full of all kinds of cool widgets and gadgets, so I'll go through them one by one. (You can also hover over the "i"con and some helpful text will be displayed.
- Response - This is displayed for Text Messages and is used as the link in emails.
- Email Description - Along with the text in 1, this is displayed for Email and Mobile App Push Messages. This allows for a bit of explanation of the response in the longer message format allowed in emails and push messages.
- Voice Prompt - This text is spoken, either using a pre-defined recording, recording your own voice, or through a Text to Speech engine. Clicking the gear icon displays choices on what to use. The keypad lets you map the response to a key on the phone keypad.
- Options dropdown - Provides additional options for this response.
- Action - This controls the event workflow and what action to take on the event based on this response. Hovering over each entry displays a helpful tool tip for each. In brief
- Record Response - Record the user's response but don't stop for other users.
- Stop Notifying Users - Stop notifying user's other devices but continue the event for other users. I'm honestly not sure how this is different than the "Record Response" entry. If you know, give a shout in the comments and I'll add something important here rather than this run on sentence that just keeps going like a winding road on a sunny day.
- Stop Notifying Target - Stop notifying other users in the target, but continue the process for other targets. This is useful for targeting multiple groups. When one user in a group responds, we stop for that group, but not for all the other groups.
- Escalate - Stop notifying user and immediately escalate to the next user (if there is one)
- Assign to User - Stop notifying other users, but do not end the process. This is useful if you want to allow a user to send another response after this initial response. I.e. to Accept a ticket, work it, then Resolve the ticket.
- End - Conclude this process - Terminates the event, no one will be further notified and no one will be able to respond.
- Contribution - Positive, Neutral, Negative or None - This indicates if the response counts for, against or not at all to a user's performance report.
- API - This is the unique UUID of the response. If we wanted to limit what responses were available to the user, we can pass a list of the response UUIDs that we want to display. Otherwise, all the responses will be displayed on all devices.
Ok, sweet. Let's go ahead and add an entry that will represent the customer indicating they would like to have one, and another for declining the offer. I know, who would skip out on these awesome muffin creations? Maybe those people have to get their hair permed or something. I had these baking while we were reading:
I've chosen a Positive contribution and to stop notifying the user. In some cases the customer might have given us their mobile phone number so once they respond on one device, we'll stop harassing them on their other devices. The other response is a "No thank you" and is a Negative contribution and again we Stop Notifying User so we don't harass them any more on this event. Some of the other actions could affect whether the rest of the customers would get notified which isn't something we want to do in this case.
Save the changes. You might get a few warnings about translations if you have multiple languages enabled. These are just telling you that there aren't translations to the other languages available in your system. They are safe to ignore, but something you'll want to take care of at some point.
Let's give it a whirl and see how things look. I'll fire up my email client and fire off a notification to our inbound email address that will kick off the event.
Success! We have responses:
When I click on the link, I see a friendly xMatters page indicating my response was accepted:
Next, we'll tell xMatters to send the response information back to the BakeSoft application to compile the list of customers who reserved muffins. Fortunately, this version of BakeSoft just happens to accept REST requests. This is great! That means we can use the "webhook" functionality in xMatters to send information. Remember way back in part 1 of this series we introduced a couple of terms? We're going to build a "webhook-only" integration (I know, we are initiating the events via email, but then we send information back via webhook to a different application, so maybe it's a hybrid?) And this part of the integration is outbound from xMatters.
Webhook-only integrations of course are made with "webhooks". These are an HTTP or HTTPS endpoint url to which xMatters will send a specially designed payload. The concept is sometimes referred to as "callbacks" and in older versions of xMoD we used the term, but have since adopted webhooks instead. The concept it the same but webhooks seems to be closer to the industry standard.
Anyhoo, navigate over to the Integration Builder tab and expand the Outbound Integrations section and hit Add.
You will be walked through a wizard that will tie the form, the webhook trigger to take and the Endpoint all together.
The webhook trigger is one of the following:
- Event status updates - Used for event status updates (creation, termination and suspension)
- Notification responses - When a user responds to a notification they received
- Device delivery updates - When a notification is delivered to a user
Select the items as in the screen shot below (see the note below about the Endpoint)
For the endpoint item, click the Edit Endpoints button and a dialog will be displayed. There, create a new endpoint and enter the base url.
After that, hit Add Outbound Integration! For details on the format of the payload sent with each type of webhook, check out the docs, in the Consume HTTP/HTTPS webhooks section.
Ok, let's test it ou! The chef sends out the email to kick things off.
And anxiously awaits the responses.... Success!
One item for improvement I can see here is using "Response Counts" to terminate the event when we've hit the limit of reservable muffins. Maybe a post for another day.
So, over all, we leveraged the response options feature of xMatters engines to send responder information to an external application via HTTP requests called "webhooks". The upshot of this is Mr. Baker can now send an email describing his muffin creations to his VIP Customers and they can respond back and those are captured in the award winning BakeSoft application.