Difference between revisions of "Webhooks"
(IFTTT going paid. :() |
|||
| (6 intermediate revisions by the same user not shown) | |||
| Line 9: | Line 9: | ||
=== Third-party services === | === Third-party services === | ||
| − | Various internet services exist, both free and paid, that allow one to trigger different actions upon receipt of a webhook post. | + | 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. | ||
| Line 17: | Line 18: | ||
Webhook alerts are only generated when a plot ends, by completion or being paused, and all four of the following conditions are met: | Webhook alerts are only generated when a plot ends, by completion or being paused, and all four of the following conditions are met: | ||
| − | :1. | + | :1. A document is being plotted with the Plot, Layers, or Resume tab (or a corresponding API mode), |
| − | :2. | + | :2. The document is being physically plotted, with preview mode disabled, |
| − | :3. | + | :3. Webhooks are enabled, for example by the checkbox in the Preview & Alerts tab of AxiDraw Control, and |
| − | :4 | + | :4. A Webhook URL is provided |
| − | In | + | In all other case, when any of the above conditions are not met, the Webhook is not posted. |
| Line 49: | Line 50: | ||
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. |
Latest revision as of 10:06, 8 February 2024
Contents
Overview: Using Webhooks with AxiDraw[edit]
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[edit]
Various internet services exist, both free and paid, that allow one to trigger different actions upon receipt of a webhook post. Common services IFTTT and 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.
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[edit]
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 (or a corresponding API mode),
- 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, when any of the above conditions are not met, the Webhook is not posted.
Some technical details[edit]
DIY; working without third-party services[edit]
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[edit]
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[edit]
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.
