Webhooks in Manuscript (previously called “URL Triggers“) allow you to specify callback URLs for various types of events. For the event type(s) you choose, Manuscript will send data about the event to the URL you specify. You may choose to have all event data sent encoded as JSON in a POST HTTP request (per the webhook convention), or structure a custom query string template to send just the variables you choose via a GET request.

Note: In Manuscript For Your Server, this feature is still called “URL Triggers” and it sends a POST values as a query string.

Creating and Editing Hooks

This feature is enabled by default in Manuscript On Demand. If you run Manuscript on your own server, JSON webhooks are not available, but you can use URL Triggers. To create or edit webhooks, log into Manuscript as an administrator and go to the Avatar Menu -> Webhooks. To create a Webhook, click Add New Hook and specify the following:

Event Types

You can create hooks which fire on any of the following event types:

  • Case Events: status changes, edits, assignments, email events
  • Discuss Topic Events: discussion thread creation, discussion post creation
  • Source Control Events: source control commits
  • Wiki Events: wiki page creation, wiki page edits
  • Time Tracking Events: time interval creation, edits, and deletion

New Hook

URL and Parameters (Query String)

Once you’ve subscribed to a set of events, you must specify the URL to which the request will be sent. You may include a query string in your URL containing parameter names and values. These can be set statically (e.g. your hook is hitting a script that accepts input from multiple sources so you put “source=manuscript” in the query string) or dynamically. When you select event types above, the list of available variables below the URL field updates. When a hook fires for a given type, any of the variable names wrapped in curly braces you have included in the URL will be replaced with their values. Note: if you are using the POST verb, you do not need to put the event variables in your URL. They are always included in the request body. See below for more details.

Hook Type (Setting the HTTP Verb)

The default for a new webhook is to send requests using the GET HTTP verb. Only the data you choose is sent in the query string you set in the URL field (above). There are also options to send as a POST, or as a bundled POST that batches webhooks together. Whichever verb you choose, hooks are processed approximately every minute but this varies based on load and account activity. Your account is limited to no more than 300 http(s) requests in any 5 minute period, so we recommend using the “Bundled POST” option so that all events are sent in one JSON body each time they’re processed instead of one request per event.

Screen Shot 2015-11-24 at 2.39.07 PM

Webhooks set to POST always send all available variables for the event type which is firing. You therefore do not need to put them in the URL as you do with a GET hook. The variables are listed right in the configuration dialog when you choose an event type. The body of a POST request consists of a JSON-encoded string. A bundled POST will send an array of events instead of one JSON object per-event: [ { eventdata }, { eventdata }, ... ]. Here is an example for a case event:

  "projectname":"Sample Project",
  "priorityname":"Must Fix",
  "eventtime":"2015-07-16 15:17:41Z",
  "changesummary":"Priority changed from '3 – Must Fix' to '5 – Fix If Time'.\r\n",
  "eventtext":"some case comment here",

This example has been formatted to make it easier to read. Actual request bodies do not include extra whitespace (they are all on one line).

Filter Criteria

If you’d like a request to be sent only if a certain set of conditions are met, you can also choose to apply a filter. A request will only be sent if the logical expression you enter in the filter field evaluates to TRUE. Filters are set up similarly to axis searches in the case list, but the syntax is a bit different. Instead of the axis names, you must use the variable names (listed below the URL field). Use an equals here instead of the colon used in list page searches.

Webhook Filter

Responses and Logging

Manuscript keeps a log of the last 24 hours of Webhook events fired and the responses. Click “View Log” on the Webhooks configuration page to access them. This is the first place to check to debug trouble with a Hook. Successful events will show an “OK” response (HTTP code 200), otherwise the error is shown. If the server returns a 410 Gone code, Manuscript immediately deletes the Hook and it does not fire again. This is designed to support services such as Zapier. You may also find “too many requests” in the log if your Hooks fire more than 300 requests in 5 minutes (1 per second). Finally, there is a “Resend” link for each hook in the log, so that you can re-try a previous missive if needed (ie, for troubleshooting).

Screen Shot 2015-11-24 at 3.17.39 PM