Difference between revisions of "Webhooks"
| Line 49: | Line 49: | ||
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. | 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. | + | '''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”. | + | '''2.''' Click the '''Create''' button to begin creation of an “applet”. |
| − | 3. Click the Add button next to “If This”. | + | '''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 | + | '''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”. | + | '''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 | + | '''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”. | + | '''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. | + | '''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 | + | '''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. | |
| − | 12. On this page is the webhook URL. | + | '''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: | 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> | <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 of Axidraw Control. | + | '''13.''' Copy and paste the full URL into the '''Webhook URL''' field in the Preview & Alerts tab of Axidraw Control. |
Revision as of 23:53, 9 January 2022
Contents
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 Inkscape-based software as well as the AxiDraw CLI and 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. Two services that we are aware of, IFTTT and Integromat, offer free tiers that support webhooks. Similar, paid, services that support webhooks include Zapier and Automate.io. Any of these services provides an interface to receive webhooks without requiring coding.
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 hackernoon for python and 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:
{ "value1" : "Document name", "value2" : "Elapsed time", "value3" : "Port" }
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 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
AxiDraw {{Value3}} finished document {{Value1}} in {{Value2}}.
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:
https://maker.ifttt.com/trigger/axidraw_done/with/key/PRIVATE_KEY
13. Copy and paste the full URL into the Webhook URL field in the Preview & Alerts tab of Axidraw Control.
