Great Ocean Media
website design - editorial & pr services - freelance journalism

adi_webhook – Webhooker

adi_webhook provides a mechanism to easily implement webhooks on Textpattern websites.

adi_webhook waits for incoming connections and, if URL variables (and values) match predefined settings, will execute the code of your choice.

It’s a bit like adi_gps in that it takes notice of URL vars, but unlike adi_gps it provides a mechanism to selectively act on the data received.

Some new tags:

The help includes example code, information for setting up your website and tips for diagnostics & testing.

The plugin was created in response to a request from Gary (giz) to process MailChimp callbacks – hence the simian examples.

Usage summary

Place the <txp:adi_webhook> ... </txp:adi_webhook> tag at the top of a special section/page (read more).

Tags

adi_webhook

This tag is the main container tag. It contains the tags to be executed when incoming connections are received. For example:

<txp:adi_webhook name="myvar1">
	...
</txp:adi_webhook>

- will execute the enclosed tags when an incoming connection contains a POST variable myvar1

Attributes

name="URL variable name"

- the optional URL variable to be present in the incoming connection. Default=”“ (all incoming connections accepted).

value="some value"

- the optional value of the URL var. Default = “” (any value acceptable). Ignored if name="".

method="HTTP method"

- comma-separated list of methods – i.e. where to look for the URL var. Default = “post” (POST). Other possibilities: “get” (GET) or “post,get” (POST & GET). If both methods specified, POST vars take preference.

form="form name"

- form to use when not in container mode. Default = “” (container mode).

debug="integer"

- generate diagnostic messages. Default = “0” (no diagnostics). Set to “1” if testing using cURL, or “2” if using browser (“2” uses <br/> line breaks for easier reading).

adi_webhook_action

This tag contains code to be executed when a URL var & value criteria are satisfied. The URL var can be different to the one specified in the adi_webhook tag and there may be more than one instance of the tag. For example:

<txp:adi_webhook name="myvar1">
	<txp:adi_webhook_action name="myvar2">
		...
	</txp:adi_webhook_action>
	<txp:adi_webhook_action name="myvar3">
		...
	</txp:adi_webhook_action>
</txp:adi_webhook>

- this will wait for an incoming connection containing a variable myvar1, and run tags if vars myvar2 or myvar3 are present.

Attributes

name="URL variable name"

- this attribute is mandatory and specifies a URL variable that must be present in the incoming connection. Default=”“ (all vars match).

value="some value"

- the optional value of the URL var. Default = “” (any value acceptable).

method="HTTP method"

- comma-separated list of methods – i.e. where to look for the URL var. Default = “post” (POST). Other possibilities: “get” or “post,get”. If both methods specified, POST vars take preference.

form="form name"

- form to use when not in container mode. Default = “” (container mode).

adi_webhook_variable

This tag outputs the value of a specified URL variable, for example:

<txp:adi_webhook_variable name="myvar2" />

Attributes

name="URL variable name"

- this attribute is mandatory and specifies a URL variable. Default=”“ (none).

method="HTTP method"

- comma-separated list of methods – i.e. where to look for the URL var. Default = “post” (POST). Other possibilities: “get” or “post,get”. If both methods specified, POST vars take preference.

adi_webhook_if_variable

This is a conditional tag and it tests the existence and/or value of a URL variable. For example, to test that GET var myvar2 has a value of “myval2”:

<txp:adi_webhook_if_variable name="myvar2" value="myval2" method="get">
	...
</txp:adi_webhook_if_variable>

Attributes

name="URL variable name"

- this attribute is mandatory and specifies a URL variable. Default=”“ (none).

value="some value"

- the optional value of the URL var. Default = “” (any value acceptable).

method="HTTP method"

- comma-separated list of methods – i.e. where to look for the URL var. Default = “post” (POST). Other possibilities: “get” or “post,get”. If both methods specified, POST vars take preference.

adi_webhook_log

This is use for diagnostic purposes to enter a message into the logfile and, in debug mode, output the message for viewing when using cURL or with browser testing.

Attributes

msg="text"

- this attribute is required and specifies a line of text to enter into the log. Default=”“ (no message).

Simple example

<txp:adi_webhook name="myvar1" value="myval1">

	<txp:adi_webhook_action name="myvar2">

		<txp:adi_webhook_log msg="*** MYVAR2 FOUND **" />

		MYVAR2 = <txp:adi_webhook_variable name="myvar2" />

		<txp:adi_webhook_if_variable name="myvar2" value="myval2">
			DO THIS ...
		<txp:else />
			DO SOMETHING ELSE ...
		</txp:adi_webhook_if_variable>

	</txp:adi_webhook_action>

</txp:adi_webhook>

In the above example:

Website setup

Your adi_webhook tags need to go at the top of a Textpattern Page, so that they can process the incoming URL vars.

It’d probably work OK if the Page went on to generate a page of HTML markup, but a tidier & safer solution would be to set up a dedicated Section/Page for receiving webhook callbacks:

  1. Create a new Section, e.g. “webhook”
  2. Create a new Page, containing your adi_webhook tags, and link it to the new section
  3. Make sure that the new section doesn’t appear in your website navigation menu!

Diagnostics

Testing using cURL

Fire off a connection to the basic example code (set up in a “webhook” section on your website):

curl --request POST --url 'http://www.example.com/webhook' '-d myvar1=myval1' '-d myvar2=myval2'

and you’ll get a response something like:

MYVAR2 = myval2
DO THIS

To see some useful diagnostics, use debug="1" on the adi_webhook tag and the same cURL command will output a shed-load of diagnostic messages.

Testing using a browser

If you connect to www.example.com/webhook in a browser, you wouldn’t normally see anything (other than a blank page) but if you set debug="2" on the adi_webhook tag, you will get something like:

2016-07-19 23:22:04 adi_webhook: ****************************************
2016-07-19 23:22:04 adi_webhook: ATTRIBUTES Array ( [var] => myvar1 [value] => myval1 [debug] => 2 )
2016-07-19 23:22:04 adi_webhook: POST Array ( )
2016-07-19 23:22:04 adi_webhook: GET Array ( )
2016-07-19 23:22:04 adi_webhook_get_var: LOOKING FOR myvar1 in POST
2016-07-19 23:22:04 adi_webhook_get_var: VAR myvar1 NOT SET

Notes:

Make sure you switch off debug for production environments.

Logfile

Regardless of the ‘debug’ attribute setting, adi_webhook maintains a diagnostic logfile in Textpattern’s temporary directory (probably textpattern/tmp).

The logfile name is based on the section in which adi_webhook is used, as well as the day of the week (0 = Sunday), e.g. “adi_webhook.my_webhook_section.3.log”.

MailChimp

Setup

Log in to your MailChimp admin:

  1. Go to the list in question
  2. Go to the list’s Settings
  3. Select Webhooks
    1. Enter the ‘Webhook URL’, e.g. “http://www.mywebsite.com/my_webhook_section”
    2. Select the “what” and “when”
    3. Click Update
  4. Whilst you’re in MailChimp, make a note of the ‘List ID’

Example 1

The code in your dedicated MailChimp webhook section/page could be:

<txp:adi_webhook name="data[list_id]" value="xxxxxxxxxx">

	<txp:adi_webhook_log msg='Incoming email: <txp:adi_webhook_variable var="data[email]" />' />

	<txp:adi_webhook_action name="type" value="subscribe">
		TAGS FOR SUBSCRIPTION ACTIONS ...
	</txp:adi_webhook_action>

	<txp:adi_webhook_action name="type" value="unsubscribe">
		TAGS FOR UNSUBSCRIPTION ACTIONS ...
	</txp:adi_webhook_action>

</txp:adi_webhook>

Notes:

Example 2

If you have more than one list, that you want to process with the same adi_webhook code, try this:

<txp:adi_webhook name="key" value="my_secret_key" method="get" debug="1">

	<txp:adi_webhook_action name="data[list_id]" value="xxxxxxxxxx">

		<txp:adi_webhook_action name="type" value="subscribe">
			TAGS FOR SUBSCRIPTION ACTIONS ...
		</txp:adi_webhook_action>

		<txp:adi_webhook_action name="type" value="unsubscribe">
			TAGS FOR UNSUBSCRIPTION ACTIONS ...
		</txp:adi_webhook_action>

	</txp:adi_webhook_action>

	<txp:adi_webhook_action name="data[list_id]" value="yyyyyyyyyy">

		<txp:adi_webhook_action name="type" value="subscribe">
			TAGS FOR SUBSCRIPTION ACTIONS ...
		</txp:adi_webhook_action>

		<txp:adi_webhook_action name="type" value="unsubscribe">
			TAGS FOR UNSUBSCRIPTION ACTIONS ...
		</txp:adi_webhook_action>

	</txp:adi_webhook_action>

</txp:adi_webhook>

Notes:

Additional information

Support and further information can be obtained from the Textpattern support forum. A copy of this help is also available online. More adi_plugins can be found here.

Version 0.1Download (Uncompressed) SupportTXP 4.5, 4.6