Webhooks in FogBugz


Follow

Overview

Webhooks in FogBugz allow you to specify callback URLs for different event types. For the selected event types, FogBugz will send the event data to the specified URL. You may choose to have all event data sent encoded as JSON in a POST HTTP request (as 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 (FYS), this feature is called “URL Triggers“,” and it sends values in POST request as query string parameters instead of using JSONs.

 


Information

Webhooks are enabled by default in FogBugz (including FogBugz On Demand).

To create or edit Webhooks, log in to FogBugz as an administrator and go to Avatar Menu > Webhooks. To create a Webhook, click Add New Hook and specify its parameters based on the information available below.

Webhooks_AddNew.jpg

 

Back to the top


Event Types

You can create webhooks 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

  • Milestone Events: milestone creation and editing

    038.png

 

Back to the top


URL and Parameters

Once you have 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 webhook is hitting a script that accepts input from multiple sources, so you put “source=fogbugz” in the query string) or dynamically.

When you select the event types, the list of available variables (query parameters) below the URL field gets updated. By clicking on a variable name, it gets copied in the URL field.

039.png

When a webhook fires for a given event 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 the Hook Types for more details.

 

Back to the top


Hook Type (Setting the HTTP Verb)

 

GET hook type

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.

 

040.png

 

POST hook type

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 body of a POST request consists of a JSON-encoded string containing the list of all variable names along with their values. The variable names are the same ones that are available for GET hooks (listed under the URL field).

In FogBugz For Your Server (FYS), POST requests send values as a query string.

Here is an example of a case event JSON:

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

 

Bundled POST hook type

A Bundled POST batches webhooks together and fires approximately every minute.

A Bundled POST will send an array of events instead of one JSON object per-event: [ { eventdata }, { eventdata }, ... ]

 

Back to the top


Filter Criteria

If you would like a request to be sent only if a specific set of conditions are met then you need to apply a filter. A request will only be sent if the logical expression you enter in the filter field is evaluated to be 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 case list page searches.

042.png

Limitations: Variable names are case sensitive and should be an exact match with your desired search values. Also, wildcards are not allowed.

Back to the top


Name of the Webhook

The webhook name will be generated automatically if left blank.

 

Back to the top


Responses, Logging and Resending

FogBugz keeps a log of the last 24 hours of Webhook events fired and the responses.

Webhooks_ViewLog.jpg

Click View Log on the Webhooks configuration page to access the logs. This is the first place to check when debugging an issue with a webhook.

  • 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 webhooks fire more than 300 requests in 5 minutes (1 per second).

There is a Resend link for each webhook in the log so that you can re-try a previous missive if needed (i.e., for troubleshooting).

043.png

 

Back to the top


Importing and Exporting Webhook Configurations

You can export existing webhooks configurations and import them using the Import or Export links available on Webhooks configuration page. The configuration will be saved in XML format.

Webhooks_ImportExport.jpg

 

Back to the top