TIL how to launch Apple Shortcuts from plaintext links across platforms.

I wanted clickable links in my plaintext notes that launch Apple Shortcuts. It’s pretty simple:

shortcuts://run-shortcut?name=ShortcutName

Spaces and special characters require URL encoding.

shortcuts://run-shortcut?name=My%20Shortcut

This works on both iOS and macOS with the one annoyance that iOS briefly shows the Shortcuts app before running. Home Screen shortcuts don’t do this because they use a different mechanism.

Input can be passed with a query parameter.

shortcuts://run-shortcut?name=ShortcutName&input=text

URL schemes vs. x-callback-url

While playing with this this, I finally understood the difference between regular URL schemes and x-callback-url.

URL scheme is a one-way trigger. Fire and forget. There’s no way to know if it succeeded.

shortcuts://run-shortcut?name=MyShortcut

x-callback-url is a round trip.

shortcuts://x-callback-url/run-shortcut?name=MyShortcut
  &x-success=mynotes://done
  &x-error=mynotes://failed
  &x-cancel=mynotes://cancelled

“Do this, then call me back with results.”

URL schemes are dropping a letter in the mail. x-callback-url is certified mail with a return receipt.

I also learned that x-callback-url isn’t an official standard, just a convention that caught on. At least in concept…I’ve never seen it actually used in practice..

For my use case (just triggering shortcuts from notes), the simple format is all I need.