Editing Webhooks

{{AxiDrawDocs}}

=== Overview: Using Webhooks with AxiDraw  ===
The AxiDraw software, starting with version 3.1, is capable of posting a '''Webhook''' (HTTP callback) at the end of a plot.  This provides a method, when used in combination with various third-party services, for generating notifications such as mobile alerts or email when the AxiDraw finishes. Webhooks can also be used for custom integration with other software or hardware, to trigger other actions that should follow a plot.

This feature is available in the main [[Axidraw_Software_Installation|Inkscape-based software]] as well as the [https://axidraw.com/doc/cli_api/ AxiDraw CLI] and [https://axidraw.com/doc/py_api/ AxiDraw Python module] APIs.


=== Third-party services ===

Various internet services exist, both free and paid, that allow one to trigger different actions upon receipt of a webhook post. Common services [http://ifttt.com IFTTT] and [http://integromat.com Integromat], offer tiers that support webhooks and do (or did) support doing so on the free service tier.. Similar, paid, services that support webhooks include Zapier and Automate.io. Any of these services provides an interface to receive webhooks without requiring coding.

[https://ntfy.sh/ ntfy] is a newer service that supports mobile notifications on iOS and Android devices. It's a free (and open source) service where you don't even need to create an account. 


=== Conditions for posting to the webhook ===

Webhook alerts are only generated when a plot ends, by completion or being paused, and all four of the following conditions are met:

:1.  A document is being plotted with the Plot,  Layers, or Resume tab,

:2.  The document is being physically plotted, with preview mode disabled,

:3. Webhooks are enabled, for example by the checkbox in the Preview & Alerts tab of AxiDraw Control, and

:4.  A Webhook URL is provided

In all other case, the Webhook is not posted.


=== Some technical details ===

==== DIY; working without third-party services ====

For custom integrations, it may be helpful to listen for and receive a webhooks with your own software. Webhooks are small-scale HTTP posts to a given URL and it is relatively straightforward (as far as these things go) to deploy a small web server for that purpose. A good article with some starting points is avaialable at [https://hackernoon.com/how-to-listen-for-webhooks-using-python-7g153uad hackernoon] for python and [https://medium.com/@BearerSH/consuming-webhooks-with-node-js-and-express-50e007fc7ae2 the Bearer blog] for node.js.  


==== Data posted ====

When the AxiDraw finishes a plot and webhooks are enabled, the software will send data by the HTTP POST method to to the URL that you specify. 
The data posted is JSON formatted and contains three key/value pairs: 

<code>{ "value1" : "Document name", "value2" : "Elapsed time", "value3" : "Port" }</code>

The elapsed time is a human-readable value with hours, minutes, and seconds. The "Port" value is that given as the Port option in the software, for example in the Config tab of AxiDraw Control. If you are using multiple AxiDraw machines, this can be used in combination with the AxiDraw Naming feature to identify which particular AxiDraw has finished plotting.


=== Setting up mobile notifications with IFTTT ===

Here, in some detail, is how to set up app-based mobile notifications using the IFTTT service. Slight variations on this can be used to select other actions once the webhook is received by IFTTT. 

'''1.''' Create a free account at [http://ifttt.com IFTTT.com]. For mobile alerts, install their mobile app as well.

'''2.''' Click the '''Create''' button to begin creation of an “applet”.

'''3.''' Click the '''Add''' button next to “If This”.

'''4.''' On the next screen, “Choose a service,” type “webhooks” in the search box. Then, click the Webhooks service to select it.

'''5.''' On the next screen, “Choose a trigger”, select “Receive a web request”.

'''6.''' The next screen, “Complete trigger fields”, asks for an Event Name. Give it a name, maybe “axidraw_done”, then click '''Create Trigger'''.

'''7.''' Click the '''Add''' button next to “Then That”.

'''8.''' Select and configure an action to trigger when a plot completes. We recommend the “Notifications” service, which gives mobile notifications from the IFTTT app, on Android or iOS. If using Notifications, choose the basic “Send a notification from the IFTTT app” option.

'''9.''' Complete the “action fields” for the action that you have selected. For Notifications, the text can be as simple as “Plot done”, or if you would like to use the data fields, as complex as 
<pre>AxiDraw {{Value3}} finished document {{Value1}} in {{Value2}}.</pre>

Click the '''Create Action''' button to finish adding it. Then click '''Continue''' to review.

'''10.''' Optionally rename the applet; click '''Finish''' to complete.

'''11.''' The completed applet should be displayed similar to here, with a brief summary of its settings. Click the “webhook” symbol on the applet; (a somewhat triangular shape with circular corners), and then click the '''Documentation''' button.

'''12.''' On this page is the webhook URL.

Fill in the {event} placeholder with your Event Name (“axidraw_done”, in our example) to get the final URL. The webhook URL typically looks like:
         <code>https://maker.ifttt.com/trigger/axidraw_done/with/key/PRIVATE_KEY</code>

'''13.'''  Copy and paste the full URL into the '''Webhook URL''' field in the Preview & Alerts tab of Axidraw Control.