Using FogBugz On Demand? We've recently rolled out a new sidebar as part of taking FogBugz forward. Please see this article for details on what's new, what's changed, and where you can find all your favorite things.

Webhooks in FogBugz (previously called “URL Triggers“) allow you to specify callback URLs for various types of events. For the event type(s) you choose, FogBugz 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 FogBugz 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 FogBugz On Demand. If you run FogBugz on your own server, JSON Webhooks are not available, but you can use URL Triggers. To create or edit Webhooks, log into FogBugz as an administrator and go to  -> 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=fogbugz” 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.

Webhook URL

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 and fires approximately every minute.

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 }, ... ].  Don’t forget, In FogBugz For Your Server POST requests send values as a query string. Here is an example for a case event:

{
  "eventtype":"CaseEdited",
  "casenumber":"123",
  "caseeventid":"2345",
  "personeditingid":"2",
  "personeditingname":"Administrator",
  "title":"Awesomeness",
  "statusid":"1",
  "statusname":"Active",
  "projectid":"1",
  "projectname":"Sample Project",
  "areaid":"1",
  "areaname":"Code",
  "fixforid":"1",
  "milestoneid":"1",
  "fixforname":"Undecided",
  "milestonename":"Undecided",
  "category":"1",
  "assignedtoid":"2",
  "assignedtoname":"Administrator",
  "priorityid":"3",
  "priorityname":"Must Fix",
  "duedate":"",
  "currentestimate":"0",
  "elapsedtime":"0",
  "version":"",
  "computer":"",
  "releasenotes":"",
  "customeremail":"",
  "eventtime":"2015-07-16 15:17:41Z",
  "eventtext":"some case comment here",
  "emailfrom":"",
  "emailto":"",
  "emailcc":"",
  "emailbcc":"",
  "emailreplyto":"",
  "emailsubject":"",
  "emaildate":"",
  "emailbodytext":"",
  "emailbodyhtml":""
}

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

FogBugz 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, FogBugz 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