Receiving webhook notifications on new Crashes, Issues and User Feedback

Your webhook

In order to receive the notifications, you need to implement a web service that can receive an array of JSON documents in the following format:

id (integer): ID of the issue
title (string): title of the issue
text (string): body of the issue. markdown format.
app (object): contains several fields, you might need name (string), the name of the application; and key (string), the app key
status (int): status of the issue. It will always be 0 (new), because the issue was just created
session (object): information about the server, most probably you don't need those
session_id (integer): ID of the session where this issue happened

Subscribing to notifications with the Dashboard

You can add a webhook to your application in the app Settings tab:

Subscribing to notifications with the API
In order to start receiving notifications, send a POST request to https://dashboard.bugfender.com/api/hook/subscribe/.
The request needs OAuth 2 authentication.
In the request you should include a JSON object with the following fields:

target_url (string): the URL of the service you created to receive notifications
event (enum): one of: new_crash, new_issue_separate, new_user_feedback
app_id (integer): the application ID. You can get this ID by looking at the last number in the URL when you visit the application in Bugfender

For example:

curl -X POST \
  https://dashboard.bugfender.com/api/hook/subscribe \
  -H 'authorization: Bearer ******' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "target_url": "https://myservice.example.com/hook",
    "event": "new_crash",
    "app_id": 1234
}'

Expect a 201 Created HTTP response, with the following JSON document format:

id (integer): the identifier of your webhook. Save this number in order to be able to unsubscribe
event (enum): the event you subscribed to
target_url (string): the URL you indicated for the webhook
app_id (string): the app ID you specified

For example:

{
    "id": 21,
    "event": "new_crash",
    "target_url": "https://myservice.example.com/hook",
    "app_id": 1234
}

The following errors can also occur:

400 Bad Request: the request wasn't understood
401 Unauthorized: no username/password supplied
403 Forbidden: the username/password specified are not valid or permission denied (double-check the app_id )

Unsubscribing from notifications
In order to unsubscribe, you need to send a DELETE request to https://dashboard.bugfender.com/api/hook/{hook_id}/. Replace {hook_id} with the identifier you got in the subscription process.
The request needs OAuth 2 authentication, just like the subscription one.
For example:

curl -X DELETE \
  https://dashboard.bugfender.com/api/hook/21/ \
  -H 'authorization: Bearer *****' \
  -H 'content-type: application/json'

If all went well, expect a 200 OK response.

The following errors can also occur:

401 Unauthorized: no username/password supplied
403 Forbidden: the username/password specified are not valid or permission denied
404 Not Found: the hook is not there (maybe you already deleted it?)

Webhook content

Webhooks will post an array of objects, depending on the type of webhook call:

For Crash/Issue/UserFeedback:

id (string)
uid (string) -- deprecated, use id instead
title (string)
text (string)
app (App object, see below)
type (enum: issue, crash, feedback)
status (enum: open, closed)
session (Session object, see below)
device (Device object, see below)
created_at (date-time)
self (url): URL to visit this object in the Bugfender dashboard

An App contains:

id (int64)
name (string)
created_at (date-time)

A Session object contains:

app_version (object, see below)
os_version (string)
language (string)

An AppVersion object contains:

version (string)
build (string)

A Device object contains:

udid (string) -- Bugfender identifier
name (string)
language (string)
user_data (object) -- user-defined key-value pairs

Webhook delivery

A webhook can contain more than one event in each call.
All events will be delivered at least once. It is possible that the same event is delivered more than once, for which case you can use the id field to detect duplicates if you need to.
If your endpoint fails to process a webhook, it will not be called again. You may combine webhooks with polling to catch events that you couldn't process in real-time.
If your endpoint fails for an extended period of time, it will be deactivated.

Troubleshooting your webhooks

If your webhook implementation does not work as expected, we recommend using a site such as https://webhook.site/ or similar, to get a real-world example of a request made by Bugfender.