Pushcut Web API

Pushcut
1

To the makers, hackers, and DIY enthusiasts like me: I just released the brand new Pushcut API!

My intention is to offer everything that is needed to integrate Pushcut to any DIY automation system you might have.

Check out the documentation here. <- You can even play around with the API through the web UI, which is pretty cool I think ; )

32

The primary use is of course to send smart notifications with dynamic content and automation actions to your iOS devices.

However, I think the coolest part is the possibility to register you own (local network) webhooks as “online actions” in Pushcut.

This way you can trigger anything in your local automation system - directly from the notification action - on your local network.

My hope is that over time there will be more and more “plug-and-play” integrations for all various DIY solutions out there (openHAB, Hass io, Node-RED, webCoRE, …)

Let me know if you are interested in collaborating on an integration, or if you want to request additions to the API.

Also, which automation system would you like to see a Pushcut integration for?

6 Likes
2

Finally got a chance to check this out, pretty cool.

Still wrapping my head around it!

1 Like
3

What is a subscription, when and how would I use one, and could you provide an example? To me it looks like it is just another name for a webhook so I don’t understand why I would use one instead of a regular url request.

Why is a valid notification name needed? Any reason why having no notification name can’t just push a completely blank notification and depend on the json to define everything?

Could you also add an option to add headers alongside the json body? httpHeaders = {'content-type': 'application/json', 'api-key': 'mypushcutapikey'}

Thanks for reading :slight_smile:

4

Oh and I am confused about the “input” key. Can this value be accessed by a webhook? How?

5

A subscription is required to access more advanced features, though a lifetime unlock is also available. A server is required to communicate with the iOS device as the iOS device is not server waiting to receive a web hook; latest at hoe server feature aside :wink:

Names are linked to actions. To make the notification actionable, the app has to know what to let you do with it.

The input key can be included in JSON and could be specified to be passed on to a webhook. So the webhook (Internet facing service) receives the request and the JSON. This is then pushed (Apple’s push servers are involved) as a notification to your device(s). The PushCut app can access the JSON data, including the value held against input. This can then be passed on to a shortcut that interacting manually with the Pushcut notification can trigger. The shortcut can then process that value.

6

Sorry I meant Subscription in terms of the web API (see the picture in the first post). It says “for registering online actions” but I’m failing to see how this is different than using a regular url webhook in an Action.

Yes, and it would know by me defining it in the web API. I can create a notification in Pushcut called “test” and give it no title, no text, and no actions. I can then send a post request to Pushcut and define the title, the text, and the actions including giving them background url webhooks. In this case the notification I created called “test” serves no purpose other than preventing a 404 error. Is there a reason why there can’t just be an “anonymous” notification?

7

Thanks for taking the time and answering but I think I need to explain better. If I have a Pushcut action with an input “42” and it does a post request to a custom webhook, then in that custom webhook how would I access the value of input = 42? Or is that value only accessible locally on the device?

8

Input

The purpose *is* to access on the local device, as far as I know. This would be passed to the “Shortcut Input” variable on a shortcut tied to and triggered from (there could be a choice) the action.

Subscription

Ah, that subscription, I really dislike non-unique terminology.

Okay, visit https://www.pushcut.io/webapi.html and then click on any of the boxes under subscription for more info, but it is setting up stuff so that you can push out to hooks on the PushCut server directly rather than having to route it via Shortcuts.

Names

Let’s say you have a home security trigger that pushes something out to the PushCut server and that then that triggers a notification on your device. The device is then to offer you some options such as to turn on house lights, open an automated door lock, activate a video feed, etc. Does the PushCut server know (via whatever you are programming in), which shortcuts to offer you when you get the notification?

I’m still trying to figure out where PushCut could fit into my routine, so I am not a big user and basing it on my rudmentary understanding of the docs and app, but my understanding is that you need to define the list of shortcuts to offer on the app itself. The server triggers those by knowing the name of the action to trigger.

You note it sending further data via background webhooks, but that isn’t the only thing PushCuts can do, and so to cover all eventualities, and I would presume to make it easier to use, the names give you a way to access a configuration you create on your device for Shortcuts, or opening a URL or the like. The way the app works would need to account for all options, not just relaying background webhook activation.

Also, does it not make sense to name entries something just from a usability standpoint?

I’ll reiterate that this is a nascent understanding on my part and that my interpretation could be wrong in at least a couple of places, but does the above sound logical as to why names could be mandatory?

9

hi fork, all good questions, let me try to create some clarity here:

You are right, it kind of is the same. “Subscriptions” (I know, bad naming on my part…) were there before and are intended to offer a programmable interface for third parties (like a DIY home automation hub) to “register” their callback webhooks with Pushcut. The same mechanism is used by the Integromat, Zapier, and Flow integrations to register “online actions”. This way, you do not have to copy/paste URLs around and can just select them in the app.

To be honest, this is just the way it is because I never cared enough to change it ; ) I am aware of the charm of a JSON-only notification, but as you say, you can easily set it up by creating a “dummy” one yourself and use it for everything. I was not so sure if I could/would have all aspects controlled by JSON so the “merged data” approach (app data + JSON overwrites) was the starting point that kept sticking…

You you mean for web request actions? On the list, and coming soon (for custom auth headers and the likes).

You can use the token replacing syntax in URLs and body ([e[input]], [%input%], or [“input”]). Check the app’s web request editor UI, it should be clear from using it there.

Did I get it all?

1 Like
10

Good enough answer for me :smile:.

Yes and awesome!

I’ll take a look at that thanks.

By the way do you think it would be possible to schedule a local notification ‘in the background’ as a url action? I don’t mean implementing scheduling in your pushcut server, but like a notification prompt with a custom “snooze” action that will set a local time-based trigger for +30 minutes, for example.

11

I’m really interested in see how other people are using the web api.

12

snoozing is on the list as a first-class feature. not sure when that will happen though…

for now, you could create a “snooze” shortcut and use the Pushcut actions to re-schedule a local notification…

1 Like