A presentation at PHP UK Conference 2018 in in London, UK by Lorna Jane Mitchell
Working with Webhooks Lorna Mitchell, IBM PHPUK, February 2018
What is a Webhook? An HTTP POST request. @lornajane
Webhooks in the Wild @lornajane
Slack Integrations @lornajane
GitHub Builds @lornajane
Fun with Zapier @lornajane
How APIs Work @lornajane
How APIs Work @lornajane
How APIs Work @lornajane
How Webhooks Work @lornajane
How Webhooks Work @lornajane
How Webhooks Work @lornajane
What About Time? @lornajane
APIs Over Time @lornajane
Webhooks Over Time @lornajane
Webhook Payloads: GitHub Push “ref”: “refs/heads/master”, “before”: “1ae6a404351cead52df24893621d82ba6ec84a1c”, “after”: “e8474d83985330fa36f8862b37ca84ada4313392”, “created”: false, “deleted”: false, “forced”: false, “compare”: “https://github.com/lornajane/demo/compare/1ae6a404351c…e847 “commits”: [ … ], “repository”: { … }, “pusher”: { … }, “sender”: { … } @lornajane
Webhook Payloads Consider the use cases: • try to include all information for common outcomes • consider impact of payload size vs potentially many followup API calls • keep data formats simple @lornajane
Webhook Security When working with webhooks: • be aware of attack vectors • always use SSL • consider shared secrets for HMAC • all good HTTP security practices apply @lornajane
Publishing Webhooks @lornajane
Publishing Webhooks Offering webhook integrations is ideal if: • you have clients polling your API a lot • it’s common for another system to react to changes in your system • you want to offer notifications for specific events @lornajane
Example App: Retro Guestbook In the olden days, we had guestbooks on our websites. My example app is a guestbook that: • allows a user to leave their name and a comment • shows the comments left so far • supports webhook notification of new comments by allowing endpoints to be registered @lornajane
Example App: Retro Guestbook @lornajane
Saving Data: Basic Process @lornajane
Saving Data: Handling Webhooks @lornajane
Saving Data: Handling Webhooks @lornajane
Saving Data: Handling Webhooks @lornajane
Saving Data: Handling Webhooks 1 2 3 4 5 6 7 8 9 10 11 $comment[‘name’] = filter_var($data[‘name’], FILTER_SANITIZE_STRIN $comment[‘comment’] = filter_var($data[‘comment’], FILTER_SANITIZE $comment[‘time’] = time(); // write comment to CouchDB… // get the list of webhooks to notify from CouchDB… // write comments and webhooks to queue $channel = $this->rabbitmq_handle->channel(); $msg = new \PhpAmqpLib\Message\AMQPMessage( json_encode([“comment” => $comment, “webhooks” => $webhooks]), $channel->basic_publish($msg, ”, ‘comments’); @lornajane
Saving Data: Handling Webhooks @lornajane
Saving Data: Handling Webhooks @lornajane
Saving Data: Handling Webhooks @lornajane
Example: Publishing Webhooks (includes excellent endpoint testing tool: http://requestb.in) @lornajane
Receiving Webhooks @lornajane
Receiving Webhooks It’s just a POST request! Advice: • DO: accept, store and acknowledge quickly • DON’T: validate or process before acknowledging @lornajane
Serverless Webhook Endpoints Serverless technology: • Functions as a Service • Scalable: ideal for bursty workloads • Pay-as-you-go, and with free tiers • PHP supported on some platforms (they all support NodeJS) @lornajane
Serverless PHP Webhook Catcher 1 function main(array $params) : array { 2 $db_url = $params[‘cloudantURL’]; 3 $incoming_body = base64_decode($params[‘__ow_body’]); 4 $data = json_decode($incoming_body, true); 5 6 echo “Saving data …\n”; 7 $server = new \PHPCouchDB\Server([“url” => $db_url]); 8 $db = $server->useDb([“name” => “incoming”]); 9 $meta = [“received” => time(), “status” => “new”]; 10 $db->create([“data” => $data, “meta” => $meta]); 11 return [“body” => “Thanks :)”]; @lornajane
Example: Receiving a Webhook @lornajane
Ngrok for Testing Webhooks https://ngrok.com/ - secure tunnel to your dev platform Use this tool to: • webhook into code running locally • inspect the request and response of the webhook • replay requests and see the responses @lornajane
Webhooks … are awesome :) @lornajane
Webhooks in Your Applications • Use them WHEN you want to notify other systems • Examples of HOW to use webhooks hopefully gave you some ideas • Webhooks are HTTP: we already understand this @lornajane
Thanks! • Feedback please! https://joind.in/ • IBM Cloud: https://www.ibm.com/cloud/ • Requestbin: http://requestb.in • Ngrok: https://ngrok.com/ • PHP Web Services from O’Reilly • Example app: https://github.com/ibm-watson-data-lab/guestbook • PHP/CouchDB: https://github.com/ibm-watson-data-lab/php-couchdb @lornajane
In an increasingly connected world, APIs are key to great tools and effective workflows. What is better than an API? A webhook of course! Webhooks are a key building block of a modern application, allowing systems to exchange data in response to events. This session gives examples of webhooks currently in use “”in the wild”“, and examines both when a webhook is useful and the internal design and structuring of webhook payloads. We’ll discuss how to work with webhooks in a scalable way regardless of technology stack; how to recieve and process incoming webhooks from an external system and how to design and publish your own for use by partners or consumers. Recommended for anyone wanting to teach their applications to play nicely with others.
