Help & Support

Get started

Check out our Guides & Examples to get an overview of what is possible with Pushcut, or jump straight to the list of possible triggers.

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, integrations, 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.

"Export for Pushcut" Can't Be Opened: Since iOS 13 any shortcut from an external link is considered "untrusted" by Apple. If you get this error, please go to Settings -> Shortcuts and check Allow Untrusted Shortcuts. You only need to do this once.

You can run Import 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 web request, an online action, or a HomeKit scene.

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 execute the associated automation. Empty actions will just dismiss or close the notification.

If you have an Apple Watch paired, an interactive notification interface will show all actions that are supported on watchOS. Please note that opening Safari, Shortcuts, or other apps is not supported on Apple Watch. However, online actions, web requests and HomeKit scenes can be executed directly from your wrist.

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. This way you can run multiple actions from one notification. 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 representation in the Pushcut app.

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

Web Requests

For http/https URLs you can enable Background Request to perform a web request instead of opening the link in Safari. The request editor lets you select details like method (GET, PUT, POST) and content type. You can pass the Input parameter in the body and URL.

This is perfect for triggering IFTTT maker webhooks, custom web services, or DIY home server APIs without opening any other app.

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.

Web requests and online actions can also be executed as background actions.

Triggering a notification

Pushcut notifications can be triggered in a variety of ways. Here is quick overview:

Locations Use the Local Triggers feature for flexible triggers based on geofences or beacons.
Scheduled Use the Local Triggers feature for daily, weekly, or monthly schedules.
Shortcuts Use the shortcut actions to schedule smart notifications dynamically from your own shortcuts.
HomeKit Use the Get contents of URL action in a HomeKit shortcut automation to send smart notifications through the Pushcut webhook. (see HomeKit guide)
IFTTT Use the Webhook service in an IFTTT applet to send smart notifications through the Pushcut webhook. (see IFTTT guide)
Zapier Use the Zapier integration to send smart notifications.
Microsoft Flow Use the Flow integration to send smart notifications.
Integromat Use the Integromat integration to send smart notifications.
Anything else Use the Web API to include Pushcut into your DIY automation setup.

Shortcut Actions

Use the Pushcut actions in your shortcuts to schedule notifications, or other shortcuts directly. You can select a time or a location event as the trigger, and pass in dynamic text, title, and input parameters. These notifications are scheduled locally on your device (ie: they do not invoke the webhook or other devices). You can review all scheduled notifications in the Pushcut app under Local Triggers -> Pending. If you set the Identifier parameter, you can cancel or override a previously scheduled notification from another shortcut.

Webhook URL

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.

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.

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.

An account can only have one active secret. You can, however, create several API-Keys and revoke them individually.

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. For location triggers, you can additionally define Do not repeat and Delay notification durations.

Background Actions

Location triggers can also be used to execute online actions and web requests directly without showing a notification. Use the Background section in the Local Triggers view to define background actions.

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 available:

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

Webhook

Trigger notifications by sending a 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. JSON bodies work with both the API and the secret webhook.

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 action triggered by this notification string
devices a list of device names this notification 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
input value that is passed as input for this action string
keepNotification when set to true, this action will not dismiss the notification (not valid for default action) boolean
shortcut the name of the shortcut this action should run string
homekit the name of a HomeKit scene this action should set (use "Home: Scene" for multiple homes) string
online the name of an online automation this action should execute (use "Integration: Trigger", as listed in the app) string
url URL that this action should open string
urlBackgroundOptions configuration for background web requests (if set, the URL is used in an HTTP request instead of opened) Options object

A URL Background Options object supports the following keys:

Key Value Type
httpMethod a valid HTTP method (GET, PUT, POST) string
httpContentType an optional content type (like "application/json") string
httpBody an optional request body string

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}]
}

{
  "actions": [{"name": "Close Garage", "homekit": "Garage Door Closed"},
              {
                "name": "Turn On Lights", 
                "url": "https://maker.ifttt.com/trigger/lights_on/with/key/noTaReaLkEY",
                "urlBackgroundOptions": {"httpMethod": "GET"}
              }]
}

{
  "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.