I was recently asked to share feedback on the Twilio API. I commented that they didn't provide a tool to mock SMS message webhooks. Twilio already provides a fantastic API Explorer in which you can tests drive many parts of the API. But mocking the webhook for a SMS getting sent to my number? It can't do that.

Of course, I'm a programmer, so I could write something up to send an HTTP request to my app. But I haven't. Why?

  1. I'm worried that my tool to mock these webhooks would get out of sync with how Twilio works. What if they deprecated a form field? What if they add a new one? (I wouldn't even notice in testing!)
  2. It's not so simple as it looks at first glance. Sure, you could just send a simple HTTP request... but they also send a X-Twilio-Signature header you need to calculate and include in the request. They respect redirects, keep cookies, and maintain a session. Suddenly a simple idea has become a complex project in it's own right.

In the past I've resorted to purchasing another phone number. I configure it as if it were live, but only using it for testing. It gets the job done and doesn't cost much. But there is a better way.


Enter Paw

Paw is a Mac app for testing and documenting APIs. You can configure any aspect of a web request, inspect the response, add notes and validations, and lots more. Today I realized I could use it to mock Twilio's webhooks. (To be fair: Twilio actually does suggest this in their webhook FAQ.)

  • Base64 encoded HMAC-SHA1? That's built in. Sending that X-Twilio-Signature header doesn't look so hard now.
HMAC-SHA1 encoded with Base64? Paw has that built in.
  • See the Paw extension I created for generating the X-Twilio-Signature, which providers the X-Twilio-Signature-Data input shown above.
  • You can specify the request method, URL params, form fields that are URL-Encoded, HTTP Basic Auth, and lot's more.
  • It's DRY. You can use variables from one part of the request in other parts of the request without needing to duplicate their values. This will make handling deprecated values like SmsSid easy.
  • It can inspect the response too. It shows the raw response, and can pretty print JSON and XML. The XML response tab is awesome when dealing with TwiML.

Try it out

I've uploaded my Paw project in case anyone else finds it useful. It represents a few hours of testing and reviewing Twilio's docs, but is still incomplete.

  • You will have to add your auth token into Paw's environment. At that point, you should probably not share the file. Instead consider using a random value and configuring your app to expect it during webhook testing.
  • Non Message APIs aren't represented at all in this project.
  • I've compared POST requests from Twilio to ensure what is in the project matches Twilio's real webhooks.
  • Twilio sends a idempotency header with what appears to be a UUID. The paw project currently sends a nonce value, but not a UUID.
  • I haven't implemented the GET requests and status callback requests.
  • Subscribe to Twilio's changelog so you aren't surprised by changes to their API.

Also see the Paw extension I created for generating the X-Twilio-Signature.