Help & Support

Get started

Check out our Guides & Examples to get an overview of what is possible with Pushcut.

Defining notifications

Use the Add Notifcation view (notification editor) in the app to define notifications as you want to see them. You can set your own notification title and body text, and give it a unique name that is used to create a URL. You can also select a distinc sound from a list for each notification.

Everytime you trigger a notification this information will be shown to you as a plain iOS notification on all your devices.

You can test your notification (even before saving) by tapping Test Notification. This happens locally on your device.

Device synchronization

By default your iCloud account will be used to link all your devices to one Pushcut account. You can change your preference in the Settings view.

Devices without an iCloud account (or with the setting turned off) will use their own isolated Pushcut account.

You can see a list of all your active devices in the Account view. All synchronized devices use the same secret, shortcuts, and online actions.

Shortcuts

If you have the Shortcuts app installed, you can import all your shortcuts into Pushcut using the Shortcuts view. Only the names of the shortcuts are actually transferred over. Using the notification editor, you can add multiple shortcuts as actions to your notification.

Importing shortcuts

The first time you run Import Shortcuts, a shortcut is installed called Export for Pushcut. The Shortcuts app will ask for your permission to download and run it only the first time.

You can run Update Shortcuts whenever shortcuts have been added, renamed, or removed. The Pushcut app will update its list and highlight shortcuts that your notifications use but are no longer available.

If you accidentally delete the Export for Pushcut shortcut, the Pushcut app will detect it and attempt to download it again (tap Import shortcuts a second time).

Actions

Each action is identified by a name and runs either a shortcut, a URL, or an online action.
Actions are displayed when you expand a Pushcut notification on your device (swipe down on the banner or 3D touch/long press in Notification Center)

Tapping an action will run the associated shortcut or open the URL on your device. Empty actions will dismiss or close the notification.

By default, executing an action will dismiss the notification. If you enable Keep Notification in the action editor, the notification will stay in Notification Center until dismissed by another action or the Dismiss button. The default action always dismisses the notification.

Default action

You can define an optional default action for each notification. It will run when you tap the notification directly (without expanding). Alternatively, you can run the default action by tapping the content area in an expanded notification.

If you do not set a default action, tapping the notification will open a message in the Pushcut app showing you the title, text, all actions, and a Dismiss button.

URLs

Many iOS applications define custom URL schemes or offer Universal Links to support automation ("deep links"). URLs always follow the scheme://path pattern, so they are easy to recognize.

It is also possible to open regular websites (like https://www.pushcut.io). Unless an app has the web URL registered as a univeral link, Safari will open the website directly. (be sure to inlcude http:// or https://)

You can use the JSON API to attach generated URLs to actions dynamically.

Examples
URL Action Kind
https://www.pushcut.io Opens the Pushcut website in Safari Web
https://twitter.com/pushcut_app Opens @pushcut_app in the twitter app if it is installed Universal
https://drive.google.com/drive/u/0/folders/ Opens a folder in the Google Drive app if it is installed Universal
omnifocus:///add?name=Task%20from%20Pushcut Adds a new task in OmniFocus Custom scheme
due:///add?title=Reminder%20from%20Pushcut Adds a new reminder in Due Custom scheme

Online actions

If you connect an integration or online service, you can trigger online automations directly from your Pushcut notification - without opening any other app.

Online actions will automatically appear in Pushcut once you activate a Pushcut trigger in a connected automation service.

Triggering a notification

After you connect Pushcut to an online automation service you can simply use the Send Notification activity or action inside the service.

For simple time or location-based triggers, Pushcut also offers built-in Local Triggers that execute on-device.

For the most versatile notification triggers, Pushcut offers an HTTP webhook that allows you to trigger your notifications by sending a POST or GET request to a secret, unique URL.

Check out our Guides & Examples to get an overview of what is possible.

The simplest way to test the webhook URL is probably by opening it in any web browser. The browser will send a GET request every time you load or refresh the page. While this will work just fine, be aware that the URL will be saved in the browser history. Make sure you are in an environment you trust before you enter your URL anywhere.

You can copy the URL by tapping Copy URL (or the URL cell) in the app. There is also an option to copy a curl statement. The command line utility curl runs on most servers as well as Macs and PCs - simply execute the statement on the command line to trigger your notification.

Tip: Use Apple's Universal Clipboard feature to paste your copied curl statement directly on your Mac.

Many automation services (like IFTTT) offer HTTP functionality ("webhooks"). Simply paste your notification's URL into the according webhook action and select POST as the method.

Virtually any common DIY home automation solution has HTTP requests integrated as well.

Use the share feature to transfer the URL and curl statement into another app (like a mail or notes app). Do not share or send your URL anywhere it can be accessed by others!

Secret

Your account comes with a secret that is used to create a URL only known to you. Anyone with this secret can push notifications to your devices. Do not share this or store it where it can by accessed by others.

If you believe somebody else has access to your secret you can use the Generate new secret feature in the Account page of the app. This will assign a new unique secret and invalidate all previously used URLs. Old URLs will no longer work - this operation is not reversible.

Currently, an account can only have one active secret.

Local Triggers

For time or location-based notifications, you can define Local Triggers in the Pushcut app directly. These are kept on-device, which means they work even when offline and do not sync to other devices connected to your account.

You can easily add local triggers inside the notification editor, or see a list of all local triggers in the separate Local Triggers view. For now, the following triggers are supported: daily, weekly (days of the week), monthly, on arrival, on departure.

Locations can be defined as a circular region on a map, or by using an iBeacon signal. For technical reasons, the minumum radius for map regions is 100 meters. It is possible to combine location and time in the form of constraints. A time-based trigger with a location constraint will only trigger while at (or not at) a configured location. Likewise, a location trigger will only fire within the specified time frame.

Integrations & Third-party services

Pushcut can be integrated with third-party automation services, both as action (ie: send notification) and as trigger (ie: thrid-party services can be triggered directly from notification actions).

After initiating the connection from a service, you will be prompted to scan a QR code with the Pushcut app and grant access. If you see the QR code page on a device with the Pushcut installed, you can simply open the link with the app. (Safari)

In the Account view, you can see all services that currently have access. By swiping left, you can revoke access for each service individually.

Here is a list of integrations that are (or will be) available:

Service Status
Zapier Early Access Start automating at zapier.com
Integromat Released Start automating at integromat.com!
Flow In Development flow.microsoft.com
IFTTT Maybe later use webhook instead - see guide
Pushcut API Released Build your own integration!

Webhook

Trigger notifications by sending an plain HTTP POST or GET request to https://api.pushcut.io/secret/notifications/notification-name

This will trigger the notification identified by notification-name on all devices linked to the account identified by secret. If everything goes well, you will get a nice 200 OK response code.

If the either secret or notification-name is wrong, you will get a 404 Not Found code with an error message like

{
  "error": "Invalid notification name."
}

Pushcut API

For more advanced functionality you can use the API at https://api.pushcut.io/v1. It supports both sending messages and registering custom webhooks (even local network URLs) to be used as online actions.

To access the API, use the Add API Key button in the Account view and include it in the HTTP header as API-Key.
Find the API documentation here.

More control with JSON

You can attach a JSON body to the POST request to dynamically adjust the notification. Dynamic titles, texts, and inputs require a Pro subscription . Passing JSON values does not change the defined notifications in your app, the information is only used for each individual push.

Make sure to set the Content-Type to application/json and that correct quotes are used!
If you have the Smart Punctuation (iOS) or Smart Quotes (macOS) feature turned on, your quotes might look like „text“ or “text”.
This is not valid JSON and will not work. Make sure your quotes look like this: "text"

Here is a list of JSON keys that are supported - they are all optional. Any other key will be ignored.

Key Value Type
text string that will be used as the notification body (instead of the defined one) string
title string that will be used as the notification title (instead of the defined one) string
defaultAction an action object describing the default action Action object
actions a list of action objects that will be merged or added to the notification array of Action objects
sound name of the sound that should be played when the notification is delivered (see list below) string
input value that is passed as input to any shortcut triggered by this notification string
devices a list of device names this notifiation should be sent to (see below) array of strings

An Action object supports the following keys:

Key Value Type
name the name of the action (not used for default action, otherwise mandatory) string
shortcut the name of the shortcut this action should run string
input value that is passed as input to this action's shortcut string
url URL that this action should open string
keepNotification when set to true, this action will not dismiss the notification (not valid for default action) boolean

The Advanced section of the app‘s notification editor lets you toggle switches for Input Parameter, Dynamic Text, and Dynamic Title.
While these are not required to enable JSON support, they are used to export an adjusted curl statement. If you tap Copy URL > Copy curl after turning these switches on you will get an executable statement with a template JSON body that will work on most systems.

Action information will be merged with the defined notification data from the app. You can add completely new actions to a notification (will be added after the defined ones), or add a value (eg: input parameter) to an action defined in the app. The name value is used to identify actions.

If you set an input value in your notification editor, it will only be used for local testing and to generate a template JSON request using the Copy curl feature.

You can set or override the notification sound by setting it to one of the following values: "vibrateOnly", "subtle", "question", "jobDone", "problem", "loud", or "lasers"

If you want to send specific notifications to selected devices only, pass a list of device names. You can see the names of devices linked to your account in the app's Account view.

Examples
{
  "title": "Rainy Day Ahead",
  "text": "Today will be 15°C and rainy. You have 6 meetings.",
  "devices": ["iPhoneXs"]
}

{
  "text": "22 files ready.",
  "input": "/images/2019-04-16"
}

{
  "defaultAction": {"input": "/myFolder"},
  "actions": [{"name": "Add reminder", "shortcut": "Add Reminder", "input": "My new reminder"},
              {"name": "Open website", "url": "https://www.pushcut.io", "keepNotification": true}]
}

{
  "sound": "lasers",
  "devices": ["iPad 11", "iPad 12.9"]
}
Error codes

You might get one of the following error codes when something is wrong with the request:

HTTP Code Message Reason
404 Not Found Invalid secret. The secret does not belong to an active account.
404 Not Found Invalid notification name. No notification is defined with this name.
400 Bad Request Specified device names invalid. At least one of the device names was not found in your account.
400 Bad Request Bad Request Something is wrong with the request, likely a malformed JSON body.
500 Internal Server Error An internal server error occured. Please try again, or contact us if this problem persists.

Contact

For further questions, or to say hello, contact us at feedback@pushcut.io.