How to Make Your App Linkable via X-Callback-Url (For App Developers)

Developers of third-party apps who want to make their apps linkable via automation without using AppleScript can do so by supporting some very simple x-callback-url APIs.

x-callback-url is a specification for interapp communication. It allows apps to define methods with parameters by way of URLs.

The specification is available at http:x-callback-url.com. It was “written by Greg Pierce, of Agile Tortoise. Ideas, contributions and comments have been provided by many — including encouragement early on by Marco Arment, Justin Williams and others.”

If you are not yet familiar with the x-callback-url specification yet, then please read it. That will make the following very easy to understand. You’ll notice from the x-callback-url website that many Mac apps implement some x-callback-url’s.

To make your app linkable, you will define two x-callback-url’s of your own. One for getting the address and title of the currently selected or open item, the other for creating a new item in your app.

Please keep in mind that it’s up to you to define the specific API, i.e., the specific URL name, and the specific names of parameters. You can have extra parameters that are not mentioned below. You don’t need to know Hook’s API. Nor do you need to understand how Hook’s integration scripts work. You’ll be defining APIs that can be used by any app, not just Hook.

Once you have defined and implemented your x-callback-urls in your app, we at CogSci Apps Corp. will be able to make use of them in Hook. (Hook Pro customers will also be able to write their own integration scripts to make Hook work with your app.)

1. URL to return the Name and Address of the current item

Please provide a URL that takes at least one input URL for the x-success case with at least two parameters:

  • name of the currently selected item (example key title or name)
  • URL of the currently selected item (example key url) in your app’s native scheme. and
  • file:// URL of the item, if the file is meaningfully available to the user via Finder.

Optionally (ideally), it would also accept an x-error URL in accordance with the 1.0 DRAFT Spec | x-callback-url specification.

Example 1: Agile Tortoise defines a Drafts /getCurrentDraft URL scheme as follows:

Return the information about the current draft loaded in the editor. To use, you must include an x-success callback URL. Drafts will call the x-success URL with uuid, url, title, content parameters with values related to the current draft. Mostly useful to access a link to the current draft from outside the app.

  • Arguments
    • none
  • Examples
    • drafts://x-callback-url/getCurrentDraft?x-success=[callbackurl]

If you examine Hook’s script for Drafts you will see how Hook uses it, which is something like this:

set hookCbURL to "hook://x-callback-url/setCurrentNode"

set draftsURLtoGetNameAndAddress to "drafts://x-callback-url/getCurrentDraft?" & "&x-success=" & hookCbURL

set getNameAndAddressScript to "open '" & draftsURLtoGetNameAndAddress & "'"

do shell script getNameAndAddressScript
return hookCbURL

But that need not concern you. It is possible to implement x-callback-url for linking without Hook. (Some developers have done it without even having a Mac.)

Example 2: Luki Labs defines a Craft app /getCurrentPageInfo? URL scheme which Hook uses. Checkout Hook’s Script Editor to see our use of it.

2. URL to add a new item in your app

If your app allows users to create new items (e.g., new notes, tasks or documents), then please provide an x-callback-url for doing this. It should accept the following parameter

  • The new item title, given by Hook (or other app that uses your x-callback-url). You’ll create a new item with this title. See <encodedTitle> in the example below

Optionally, it may also accept

  • content . Your app would insert this content in the new item. Hook likes to place a linkback (in Markdown or RTF), for instance, inside the items it creates.
  • tag names.
  • any other parameters you want. It’s your API after-all.

It should return

  • The new item’s title (because you might have not accepted the precise title you were asked)
  • the new item’s URL native to your app.
  • if available, the file:// URL (path) of the new item.

It may also return additional parameters, which Hook might ignore. (If they’re relevant we’ll try to use them sensibly).

Example 1: Luki Labs defines a Craft app /getCurrentPageInfo? URL scheme which Hook uses.

Their example:

craftdocs://createdocument?spaceId=zsomborf&title=hello&content=this%20is%20content&folderId=

possible values in result from the latter: blockld; spaceld; link.

In case you’re curious See Hook’s Script Editor to see our use of it. Here’s what that might look like:

craftdocs://createdocument?title=<encodedTitle>&x-success=<hookCbURL>&x-error=<hookCbURLError>

  • <encodedTitle> is from Hook, used by Craft to create a new doc.
  • <hookCbURL> is our callback. You don’t actually need to know this, but just FYI we do the following before passing this parameter to that callback URL:

set hookCbURL to "hook://x-callback-url/link-to-new" set hookCbURL to hookCbURL & "%3FurlKey%3Dlink" & "%26src%3D" & encodedSrc & "%26title%3D" & encodedTitle

In a nutshell

So, in a nutshell by providing the first x-callback-url (URL to return the Name and Address of the current item), you will enable Hook to discover the name and URL of the currently selected or open item in your app.

By providing the second one, you will enable Hook to

  1. create an item in your app with a given name;
  2. know what the URL of the currently selected item is; and
  3. optionally write some information in the newly created item.

Each method will in turn allow Hook to create “hooks”, bidirectional links, between information your app and information that is potentially elsewhere.

Questions?

If you have any questions along the way, please feel free to contact us to let us.

Then please let us know… 😊

Once you’ve implement the x-callback-url, please contact us to let us know. We’ll be happy to have a look to add integration to Hook. If you could provide a coupon code for your app for a developer and QA here that would be grand. You can even share your new API on the Hook Productivity Forum (automation category). The community will be delighted to discover another linkable app. Many automators participate in our forum who might even jump in and share an integration script that can be used inside Hook’s Integration Scripts preferences panel.