adding basic information on webhooks

mattmakai · mattmakai · commit f78ab0548a71 · 2014-05-26T13:05:50.000-04:00
diff --git a/application-programming-intefaces.html b/application-programming-intefaces.html
@@ -48,7 +48,17 @@ <h2>Why are APIs important?</h2>
 programs and libraries exist to rip data out of HTML but it's simpler
 to consume data through APIs.</p>
 <h2>Webhook</h2>
-<p>A webhook is a user-defined HTTP callback.</p>
+<p>A webhook is a user-defined HTTP callback to a URL that executes when on a 
+system condition is met. The call alerts the second system and often passes
+data as well.</p>
+<p>Webhooks are important because they enable two-way communication initiation 
+for APIs. Webhook flexibility comes in from their definition by the API user
+instead of the API itself.</p>
+<p>For example, in the <a href="https://www.twilio.com/api">Twilio API</a> when a text 
+message is sent to a Twilio phone number Twilio sends an HTTP POST request 
+webhook to the URL specified by the user. The URL is defined in a text box
+on the number's page on Twilio as shown below.</p>
+<p><img src="theme/img/twilio-webhook-definition.jpg" width="100%" alt="Webhook definition in the Twilio API." class="technical-diagram" /></p>
 <h2>API open source projects</h2>
 <ul>
 <li><a href="https://github.com/wordnik/swagger-core">Swagger</a> is an open source project 
diff --git a/change-log.html b/change-log.html
@@ -47,6 +47,7 @@ <h1>Change Log</h1>
 <h2>2014</h2>
 <h3>May</h3>
 <ul>
+<li>Updated APIs page with basic information on webhooks.</li>
 <li>Added learning checklist for source control, application dependencies,
   configuration management and NoSQL data stores.</li>
 <li>Moving learning checklists to the bottom of the pages since they are 
diff --git a/feeds/all.atom.xml b/feeds/all.atom.xml
@@ -1,2 +1,2 @@
 <?xml version="1.0" encoding="utf-8"?>
-<feed xmlns="http://www.w3.org/2005/Atom"><title>Matt Makai</title><link href="http://www.fullstackpython.com/" rel="alternate"></link><link href="http://www.fullstackpython.com/feeds/all.atom.xml" rel="self"></link><id>http://www.fullstackpython.com/</id><updated>2014-05-26T11:50:37Z</updated></feed>
+<feed xmlns="http://www.w3.org/2005/Atom"><title>Matt Makai</title><link href="http://www.fullstackpython.com/" rel="alternate"></link><link href="http://www.fullstackpython.com/feeds/all.atom.xml" rel="self"></link><id>http://www.fullstackpython.com/</id><updated>2014-05-26T13:05:42Z</updated></feed>
diff --git a/source/content/pages/06-apis/0601-application-programming-interfaces.markdown b/source/content/pages/06-apis/0601-application-programming-interfaces.markdown
@@ -29,7 +29,21 @@ to consume data through APIs.
 
 
 ## Webhook
-A webhook is a user-defined HTTP callback.
+A webhook is a user-defined HTTP callback to a URL that executes when on a 
+system condition is met. The call alerts the second system and often passes
+data as well.
+
+Webhooks are important because they enable two-way communication initiation 
+for APIs. Webhook flexibility comes in from their definition by the API user
+instead of the API itself.
+
+For example, in the [Twilio API](https://www.twilio.com/api) when a text 
+message is sent to a Twilio phone number Twilio sends an HTTP POST request 
+webhook to the URL specified by the user. The URL is defined in a text box
+on the number's page on Twilio as shown below.
+
+<img src="theme/img/twilio-webhook-definition.jpg" width="100%" alt="Webhook definition in the Twilio API." class="technical-diagram" />
+
 
 
 ## API open source projects
diff --git a/source/content/pages/10-misc/1005-change-log.markdown b/source/content/pages/10-misc/1005-change-log.markdown
@@ -24,6 +24,7 @@ the
 
 ## 2014
 ### May
+* Updated APIs page with basic information on webhooks.
 * Added learning checklist for source control, application dependencies,
   configuration management and NoSQL data stores.
 * Moving learning checklists to the bottom of the pages since they are 
diff --git a/source/theme/static/img/twilio-webhook-definition.jpg b/source/theme/static/img/twilio-webhook-definition.jpg
diff --git a/theme/img/twilio-webhook-definition.jpg b/theme/img/twilio-webhook-definition.jpg

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`<?xml version="1.0" encoding="utf-8"?>`
`2`		`-<feed xmlns="http://www.w3.org/2005/Atom"><title>Matt Makai</title><link href="http://www.fullstackpython.com/" rel="alternate"></link><link href="http://www.fullstackpython.com/feeds/all.atom.xml" rel="self"></link><id>http://www.fullstackpython.com/</id><updated>2014-05-26T11:50:37Z</updated></feed>`
	`2`	`+<feed xmlns="http://www.w3.org/2005/Atom"><title>Matt Makai</title><link href="http://www.fullstackpython.com/" rel="alternate"></link><link href="http://www.fullstackpython.com/feeds/all.atom.xml" rel="self"></link><id>http://www.fullstackpython.com/</id><updated>2014-05-26T13:05:42Z</updated></feed>`