API testing and monitoring has traditionally focused solely on outbound requests that simulate what a client of a particular API or endpoint would experience. But APIs are increasingly becoming a two-way conversation, with data flowing into apps asynchronously based on events happening (e.g. GitHub commits, Twilio text messages received, bots receiving requests, etc.). The most popular way this occurs is via a pattern known as webhooks.
Testing a webhooks implementation can be difficult. While you can exercise specific endpoints that consume an event payload (Runscope is great at this), generating test events that mimic real-world conditions is a manual process. What we need is an API testing tool that understands data going out via API calls, but also data coming in via asynchronous callbacks, and the relationship between the two.
Introducing Monitoring and Testing for Webhooks
Today we've added a new feature to our API testing and monitoring lineup that allows you to combine outgoing API calls with incoming callback requests. To understand how this works, let's take a look at a simple example.
Testing Twilio Status Callback URLs
Twilio is an API that allows developers to add communications (voice, text, video) features to their applications. One of the most popular products they offer is their SMS API. When sending SMS, it's really important to know whether or not a message was delivered. The Twilio API offers a "Status Callback URL" that will notify your app of delivery status after you send a message. Delivering a message takes a little bit of time so it's not possible to include a delivery status in the response to the original API call. Instead, you can pass a URL to be notified at asynchronously once the delivery attempt is completed.
To test this scenario, we can create a test that sends an SMS message via an outbound API call, then waits for a callback request containing the delivery status using the new Incoming Request Step type:
Incoming Request Steps can be validated just like the responses of outgoing API calls. In this case, we're checking for a form POST parameter named MessageStatus to make sure the value is correct. You can also check JSON attributes, extract and store values to use in subsequent requests with variables, or write more advanced assertions with JavaScript and the Chai Assertion library.
Testing Conditional Webhooks
Clearbit is one of our favorite new services. We make heavy use of their Enrichment API for qualifying leads. When looking up an email address, sometimes you get an immediate response (if it has been looked up recently) but other times you'll get a callback once the data has been retrieved. Using incoming requests combined with a condition, we can test this scenario as well:
If our initial request returns a 200 OK, we can assert on the response and extract data for subsequent requests. If we get a 202 Accepted back, we know that we'll get the details via the webhook URL and can handle the data there instead.
These are just a couple examples of how you can use Incoming Request steps to verify your webhook and callback workflows. There are many other possibilities including testing bot responses, simple API integration and workflow automation, and much more.
Now Available for All Runscope Accounts
Incoming Request steps are now available for all free and paid Runscope accounts. If you're new to Runscope, be sure to sign up for your free trial to try it out. You'll see the "Add Incoming Step" option at the bottom of the test steps editor. As always, if you have any questions or need help getting started, contact our support team any time.