Creating an ASP.NET MVC Webhook Project
David Prothero
Webhooks - URLs you expose to handle callbacks - are pivotal to harnessing the power of Twilio in your web application. A powerful concept, webhooks also happen to be very easy to create in your ASP.NET MVC Project. We'll prove it - let's expose some webhooks in ASP.NET MVC and receive some text messages!
Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks, or status callbacks. For more, check out our guide to Getting Started with Twilio Webhooks. Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.
Webhooks and ASP.NET MVC Projects
For one webhook example, when receiving an SMS (text) message, Twilio will call your application with data describing the incoming message. The same process applies for Programmable Voice, Programmable Chat, Programmable Video, and the other Twilio APIs.
This guide will walk you through setting up a basic project for handling incoming webhook requests in your project. The screenshots in the steps shown were made with Visual Studio 2015, but the process is much the same in Visual Studio 2013 and 2017.
Create the Project
Create a new ASP.NET MVC project that can handle incoming requests from Twilio. Open up Visual Studio and select File... New Project. Find the ASP.NET Web Application template for C# as shown here:
Name the project and solution to suit your needs.
After clicking OK, you will be prompted for the ASP.NET Project details:
An "Empty" project is all you need if you will only be handling webhook requests, but be sure to select the MVC option for adding folders and core references. Finally, select “Host in the cloud” if you want to be able to easily publish your app to Azure. Twilio will need a publicly reachable URL to which to send requests and hosting in Azure fits this bill.
Hosting with Azure
If you select the option to host in Azure, the next dialog to pop up will be the Azure Web App Settings:
At this point you will need to login to your Microsoft Azure subscription. Once you’re logged in, you must enter a Web App name that will be globally unique (you will get a green checkmark once you’ve selected a unique name). Keep track of that name for later, as it will be part of the URL for your webhook.
You will likely need to create a new App Service plan and Resource group, unless you’ve already been deploying your own Web Apps to Azure. You can select whatever Region you like and a Database server based on whether you will need one for your app. If you will just be calling other API's, then you likely do not need one.
Once you click OK, Visual Studio will create your new project and publish your app to Azure. You will know it is complete by looking at the "Azure App Service Activity" tab in Visual Studio:
NuGet Packages
To finish off the framing of the project, you need to install a few dependencies via the NuGet Package Manager. This can be most quickly accomplished using the Console, which you can reach by choosing the Tools menu, NuGet Package Manager, and Package Manager Console.
To get the Twilio helper libraries you will need use the following command. It requests the Twilio.AspNet.Mvc package, telling NuGet to get the latest versions of the dependent Twilio package:
Install-Package Twilio.AspNet.Mvc -DependencyVersion HighestMinor
Create a "Hello World" Controller
To explore how to handle webhooks in ASP.NET MVC, this guide will use the Twilio Programmable SMS product. When Twilio receives an SMS message at a phone number that you own it will call your webhook. We can listen for this webhook using an ASP.NET MVC Controller.
Find the “Controllers” folder of your new project in the Solution Explorer:
Right-click the folder and select Add... Controller... Choose an empty MVC 5 Controller:
Name the controller whatever makes sense for your use case:
Update your using statements to import the Twilio namespaces:
using Twilio.AspNet.Common;
using Twilio.AspNet.Mvc;
using Twilio.TwiML;
Then, change your controller class to inherit from TwilioController instead of the default Controller provided by ASP.NET MVC:
public class HelloWorldController : TwilioController
Next, modify the Index action method to have the [HttpPost] attribute, a return value of TwiMLResult and an SmsRequest parameter:
[HttpPost]
public TwiMLResult Index(SmsRequest request)
The SmsRequest class is defined in the Twilio.AspNet.Mvc library and will contain all of the deserialized parameters that Twilio will pass to us. If you were responding to a voice call, then you would use the VoiceRequest class.
Twilio expects your webhook to return TwiML (XML), but you don’t need to code the XML by hand. You can make use of the MessagingResponse and VoiceResponse classes (from the Twilio library) to build a TwiML response programmatically. These classes contain methods corresponding to the TwiML verbs that Twilio understands.
Update your action method as follows:
After adding the “Hello World” message, call the TwiML function provided by TwilioController. This is analogous to calling View(myModel) in a typical ASP.NET MVC controller action.
Test and Debug Locally
Run your application from within Visual Studio to view your application in the browser. In this case, there isn't a default home page for your app:
You might think to add /HelloWorld (or whatever you named your controller) to the URL in the browser. You would be on the right track, but this will still return a 404 because your browser will be doing a GET request instead of a POST request. You can break out a tool like Fiddler or Postman to test POST requests to your newly created controller, but there is a simpler way that’s built right into Windows - PowerShell. Open a new PowerShell window and run the following command:
Invoke-WebRequest http://localhost:XXXXX/HelloWorld -Method POST
Replace the XXXXX with the random port number that Visual Studio assigned to your web app. You can find this in the URL when Visual Studio first launched your app in the browser. Change HelloWorld to whatever you named your controller (without the Controller suffix).
This will return a PowerShell object with the response from your controller:
StatusCode : 200
StatusDescription : OK
Content : <?xml version="1.0" encoding="utf-8"?>
<Response>
<Message>Hello World</Message>
</Response>
RawContent : ...
You should be able to see the raw XML response we are returning in the Content property. Pro-tip: you can see just the Content property with a single command:
(Invoke-WebRequest http://localhost:XXXXX/HelloWorld -Method POST).Content
(Want more detailed information on using PowerShell with HTTP Requests or Twilio? Try our guide to sending HTTP Requests with PowerShell).
Deploy and Test Your ASP.NET MVC App
Publish to Azure
To publish your app to Azure, find the “Azure App Service Activity” tab in Visual Studio and click the Publish button:
Once the publish is complete, you can test your app from PowerShell again:
Invoke-WebRequest https://yourapp.azurewebsites.net/HelloWorld -Method POST
Replace yourapp with the name you selected for your Azure Web App and HelloWorld with the name of your controller.
Assuming that works, you can move on to attaching your webhook to a phone number in Twilio. (To learn how to debug your webhook locally without deploying, see our guide on that topic.)
Configure a Twilio Number
If you haven’t already purchased a Twilio phone number, do so now. Once that is done, you can configure the Messaging Webhook like so:
Use the same URL for your Azure Web App that you tested in PowerShell earlier. Be sure to click the SAVE button to save your configuration for the phone number.
Test it out! Send any text message to your number and you should get back the ‘Hello World’ response:
Conclusion
This walkthrough should get you most of the way down the path to handling webhooks in ASP.NET MVC projects. For more in-depth examples, see the complete applications for a variety of Twilio use cases that are documented in our Tutorials.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
