Testing Webhooks Locally for Amazon SNS

In a recent post, I talked about Receiving Amazon SNS Messages in PHP. I showed you how to use the SNS Message and MessageValidator classes in the AWS SDK for PHP to handle incoming SNS messages. The PHP code for the webhook is easy to write, but can be difficult to test properly, since it must be deployed to a server in order to be accessible to Amazon SNS. I’ll show you how you can actually test your code locally with the help of a few simple tools.

Testing Tools

To test the code I wrote for the blog post, I used PHP’s built-in web server (available in PHP 5.4 and later) to serve the code locally. I used another tool called ngrok to expose the locally running PHP server to the public internet. Ngrok does this by creating a tunnel to a specified port on your local machine.

You can use PHP’s built-in web server and ngrok on Windows, Linux, and Mac OS X. If you have PHP 5.4+ installed, then the built-in server is ready to use. To install ngrok, use the simple instructions on the ngrok website. I work primarily in OS X, so you may need to modify the commands I use in the rest of this post if you are using another platform.

Setting Up the PHP Code

First, you’ll need the PHP code that will handle the incoming messages. My post about receiving SNS messages provides a complete code example for doing this.

Let’s create a new folder in your home directly to use for this test. We’ll also install Composer, the AWS SDK for PHP, create a directory for the webroot, and create files for the PHP code and a log.

mkdir ~/sns-message-test && cd ~/sns-message-test
curl -sS https://getcomposer.org/installer | php
php composer.phar require aws/aws-sdk-php:~2.6.0
touch messages.log
mkdir web && touch web/index.php

Now take the PHP code from the other blog post and put it in index.php. Here is that same code, but with the require statement needed to load the SDK with our current file structure. I am also going to update the code to log the incoming messages to a file so we can easily see that the messages are being handled correctly.

<?php

require __DIR__ . '/../vendor/autoload.php';

use AwsSnsMessageValidatorMessage;
use AwsSnsMessageValidatorMessageValidator;
use GuzzleHttpClient;

// Make sure the request is POST
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    die;
}

try {
    // Create a message from the post data and validate its signature
    $message = Message::fromRawPostData();
    $validator = new MessageValidator();
    $validator->validate($message);
} catch (Exception $e) {
    // Pretend we're not here if the message is invalid
    http_response_code(404);
    die;
}

if ($message->get('Type') === 'SubscriptionConfirmation') {
    // Send a request to the SubscribeURL to complete subscription
    (new Client)->get($message->get('SubscribeURL'))->send();
}

// Log the message
$file = new SplFileObject(__DIR__ . '/../messages.log', 'a');
$file->fwrite($message->get('Type') . ': ' . $message->get('Message') . "n");

Creating an Amazon SNS Topic

Before you can perform any tests, you must set up an Amazon SNS topic. You can do this easily in the AWS Management Console by following the Getting Started with Amazon Simple Notification Service guide. This guide also shows how to subscribe to a topic and publish a message, which you will also need to do in a moment.

Setting Up the Server

OK, we have an Amazon SNS topic ready and all of the files we need in place. Now we need to start up the server and make it accessible to Amazon SNS. To do this, create 3 separate terminal windows or tabs, which we will use for 3 separate long-running processes: the server, ngrok, and tailing the messages log.

Launching the PHP Built-in Server

In the first terminal window, use the following command to start up the PHP built-in web server to serve our little test webhook. (Note: you can use a different port number, just make sure you use the same one with ngrok.)

php -S 127.0.0.1:8000 -t web/

This will create some output that looks something like the following:

PHP 5.4.24 Development Server started at Mon Mar 31 11:02:14 2014
Listening on http://127.0.0.1:8000
Document root is /Users/your-user/sns-message-test/web
Press Ctrl-C to quit.

If you access http://127.0.0.1:8000 from your web browser, you will likely see a blank page, but that request will show up in this terminal window. Since our code is set up to respond only to POST requests, we will see the expected behavior of a 405 HTTP code in the response.

[Mon Mar 31 11:02:44 2014] 127.0.0.1:61409 [405]: /

Creating a Tunnel with ngrok

In the second terminal window, use the following command to create an ngrok tunnel to the PHP server. Use the same port as you did in the previous section.

ngrok 8000

That was easy! The output of this command will contain a publicly accessible URL that forwards to your localhost.

Tunnel Status                 online
Version                       1.6/1.5
Forwarding                    http://58565ed9.ngrok.com -> 127.0.0.1:8000
Forwarding                    https://58565ed9.ngrok.com -> 127.0.0.1:8000
Web Interface                 127.0.0.1:4040
# Conn                        1
Avg Conn Time                 36.06ms

ngrok also provides a small web app running on localhost:4040 that displays all of the incoming requests through the tunnel. It also allows you to click a button to replay a request, which is really helpful for testing and debugging your webhooks.

Tailing the Message Logs

Let’s use the third terminal window to tail the log file that our PHP code writes the incoming messages to.

tail -f messages.log

This won’t show anything yet, but once we start publishing Amazon SNS messages to our topic, they should be printed out in this window.

Testing the Incoming SNS Messages

Now that everything is running and wired up, head back to the Amazon SNS console and subscribe the URL provided by ngrok as an HTTP endpoint for your SNS topic.

If all goes well, you should see output similar to the following on each of the 3 terminal windows.

PHP Server:

[Tue Apr  1 08:51:13 2014] 127.0.0.1:50190 [200]: /

ngrok:

POST /                        200 OK

Log:

SubscriptionConfirmation: You have chosen to subscribe to the topic arn:aws:sns:us-west-2:01234567890:sdk-test. To confirm the subscription, visit the SubscribeURL included in this message.

Back in the SNS console, you should see that the subscription has been confirmed. Next, publish a message to the topic to test that normal messages are processed correctly. The output should be similar:

PHP Server:

[Tue Apr  1 10:08:14 2014] 127.0.0.1:51235 [200]: /

ngrok:

POST /                        200 OK

Log:

Notification: THIS IS MY TEST MESSAGE!

Nice work!

Cleaning Up

Now that we are done, be sure to shutdown (Ctrl+C) ngrok, tail, and the local php server. Unsubscribe the defunct endpoint you used for this test, or just delete the SNS topic entirely if you aren’t using it for anything else.

With these tools, you can now test webhooks in your applications locally and interact with Amazon SNS more easily.