feat(verification webhooks): update hal browser documentation

Author: bethesque

lib/pact_broker/doc/controllers/app.rb

@@ -11,16 +11,26 @@ class App < Padrino::Application
         set :root, File.join(File.dirname(__FILE__), '..')
         set :show_exceptions, true
 
+        MAPPINGS = {
+          'webhooks-create' => 'webhooks',
+          'webhooks-webhooks' => 'webhooks',
+          'pact-webhooks' => 'webhooks',
+        }.freeze
+
         helpers do
+          def view_name_for rel_name
+            MAPPINGS[rel_name] || rel_name
+          end
+
           def resource_exists? rel_name
-            File.exist? File.join(self.class.root, 'views', "#{rel_name}.markdown")
+            File.exist? File.join(self.class.root, 'views', "#{view_name_for(rel_name)}.markdown")
           end
         end
 
         get ":rel_name" do
           rel_name = params[:rel_name]
           if resource_exists? rel_name
-            markdown rel_name.to_sym, {:layout_engine => :haml, layout: :'layouts/main'}, {}
+            markdown view_name_for(rel_name).to_sym, {:layout_engine => :haml, layout: :'layouts/main'}, {}
           else
             response.status = 404
           end

lib/pact_broker/doc/views/pact-webhooks.markdown

@@ -1,6 +1,8 @@
 # Webhooks
 
-Allowed methods: GET, POST, DELETE
+Allowed methods (collection resource): `GET`, `POST`
+
+Allowed methods (individual resource): `GET`, `PUT`, `DELETE`
 
 ### Creating
 
@@ -9,9 +11,12 @@ Allowed methods: GET, POST, DELETE
 2. Click the "NON-GET" button for the "pact-webhooks" relation.
 3. Paste in the webhook JSON (example shown below) in the body section and click "Make Request".
 
-An example webhook to trigger a Bamboo job.
+An example webhook to trigger a Bamboo job when a contract has changed.
 
     {
+      "events": [{
+        "name": "contract_content_changed"
+      }],
       "request": {
         "method": "POST",
         "url": "http://master.ci.my.domain:8085/rest/api/latest/queue/SOME-PROJECT?os_authType=basic",
@@ -26,6 +31,9 @@ An example webhook to trigger a Bamboo job.
 A request body can be specified as well.
 
     {
+      "events": [{
+        "name": "contract_content_changed"
+      }],
       "request": {
         "method": "POST",
         "url": "http://example.org/something",
@@ -37,6 +45,33 @@ A request body can be specified as well.
 
 **BEWARE** The password can be reverse engineered from the database, so make a separate account for the Pact Broker to use, don't use your personal account!
 
+#### Event types
+
+`contract_content_changed:` triggered when the content of the contract has changed since the previous publication. Uses plain string equality, so changes to the ordering of hash keys, or whitespace changes will trigger this webhook.
+
+`provider_verification_published:` triggered whenever a provider publishes a verification.
+
+### Dynamic variable substitution
+
+The following variables may be used in the request parameters or body, and will be replaced with their appropriate values at runtime.
+
+`${pactbroker.pactUrl}`: the "permalink" URL to the newly published pact (the URL specifying the consumer version URL, rather than the "/latest" format.)
+
+Example usage:
+
+    {
+      "events": [{
+        "name": "contract_content_changed"
+      }],
+      "request": {
+        "method": "POST",
+        "url": "http://example.org/something",
+        "body": {
+          "thisPactWasPublished" : "${pactbroker.pactUrl}"
+        }
+      }
+    }
+
 ### Testing
 
 To test a webhook, navigate to the webhook in the HAL browser, then make a POST request to the "execute" relation. The response or error will be shown in the window.