From c2b31b419275c41bad7238e29a1f1e335d4d1d1e Mon Sep 17 00:00:00 2001 From: Beth Skurrie Date: Fri, 15 Dec 2017 15:40:35 +1100 Subject: [PATCH] feat(verification webhooks): update hal browser documentation --- lib/pact_broker/doc/controllers/app.rb | 14 +++++- .../doc/views/pact-webhooks.markdown | 50 ------------------- .../doc/views/webhooks-create.markdown | 38 -------------- .../doc/views/webhooks-webhooks.markdown | 15 ------ lib/pact_broker/doc/views/webhooks.markdown | 39 ++++++++++++++- 5 files changed, 49 insertions(+), 107 deletions(-) delete mode 100644 lib/pact_broker/doc/views/pact-webhooks.markdown delete mode 100644 lib/pact_broker/doc/views/webhooks-create.markdown delete mode 100644 lib/pact_broker/doc/views/webhooks-webhooks.markdown diff --git a/lib/pact_broker/doc/controllers/app.rb b/lib/pact_broker/doc/controllers/app.rb index a9e3a213e..7a4573aec 100644 --- a/lib/pact_broker/doc/controllers/app.rb +++ b/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 diff --git a/lib/pact_broker/doc/views/pact-webhooks.markdown b/lib/pact_broker/doc/views/pact-webhooks.markdown deleted file mode 100644 index 98f98d7f2..000000000 --- a/lib/pact_broker/doc/views/pact-webhooks.markdown +++ /dev/null @@ -1,50 +0,0 @@ -# Webhooks - -Allowed methods: GET, POST, DELETE - -### Creating - -1. To create a webhook, in the HAL Browser, navigate to the pact you want to create the webhook for -(Click "Go to Entry Point", then select "latest-pacts", then select the pact you want to create the webhook for.) -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. - - { - "request": { - "method": "POST", - "url": "http://master.ci.my.domain:8085/rest/api/latest/queue/SOME-PROJECT?os_authType=basic", - "username": "username", - "password": "password", - "headers": { - "Accept": "application/json" - } - } - } - -A request body can be specified as well. - - { - "request": { - "method": "POST", - "url": "http://example.org/something", - "body": { - "some" : "json" - } - } - } - -**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! - -### 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. - -### Deleting - -Send a DELETE request to the webhook URL. - -### Updating - -Send a PUT request to the webhook URL with all fields required for the new webhook. diff --git a/lib/pact_broker/doc/views/webhooks-create.markdown b/lib/pact_broker/doc/views/webhooks-create.markdown deleted file mode 100644 index 1a75cbfd8..000000000 --- a/lib/pact_broker/doc/views/webhooks-create.markdown +++ /dev/null @@ -1,38 +0,0 @@ -# Create a webhook - -Allowed methods: POST - -1. Click the "NON-GET" button for the "pb:create" 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. - - { - "request": { - "method": "POST", - "url": "http://master.ci.my.domain:8085/rest/api/latest/queue/SOME-PROJECT?os_authType=basic", - "username": "username", - "password": "password", - "headers": { - "Accept": "application/json" - } - } - } - -A request body can be specified as well. - - { - "request": { - "method": "POST", - "url": "http://example.org/something", - "body": { - "some" : "json" - } - } - } - -**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! - -### 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. diff --git a/lib/pact_broker/doc/views/webhooks-webhooks.markdown b/lib/pact_broker/doc/views/webhooks-webhooks.markdown deleted file mode 100644 index 96f2edbaa..000000000 --- a/lib/pact_broker/doc/views/webhooks-webhooks.markdown +++ /dev/null @@ -1,15 +0,0 @@ -# Webhooks - -Allowed methods: GET, DELETE - -### 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. - -### Deleting - -Send a DELETE request to the webhook URL. - -### Updating - -Send a PUT request to the webhook URL with all fields required for the new webhook. diff --git a/lib/pact_broker/doc/views/webhooks.markdown b/lib/pact_broker/doc/views/webhooks.markdown index 98f98d7f2..65a43736f 100644 --- a/lib/pact_broker/doc/views/webhooks.markdown +++ b/lib/pact_broker/doc/views/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.