Webhooks

Webhooks allows you to build integrations that subscribe to specific Accelo events. Upon triggering, we'll HTTP POST a payload to your registered callback url containing event meta data and a resource url. The resource url can be used by your application to query the individual resource that fired the event. This is commonly referred to as Notification Webhooks.

There's currently no limit on webhooks and they can be installed per deployment from an individual users account using the webhooks control panel. The control panel can be accessed from the administration configuration page → api → webhooks.

Access

Only pro users and up can utilise webhooks. This doesn't mean other users cannot register them on behalf but webhooks will only fire on objects the owner of the object has view access to. For example, If Alice registers to receive notifications whenever a task assignee changes. She will not receive notifications for any tasks she cannot view from within Accelo.

Events

When subscribing to webhooks you choose an event that you would like to receive payloads for. Each event corresponds to a certain set of actions on a per object basis. The available events are:

Payloads

Each event will bundle together a payload containing the details of what happens and a resource url pointing you where to go for more fields of the object affected.

All events will contain an id and all non-delete events will contain a resource_url. For example,

{
    "id": 1,
	"resource_url": "https://bobs-burgers.api.accelo.com/api/v0/issues/1.json"
}

Using your application you should then query the resource url using your registered tokens to gather more information about the affected issue.

Delivery Headers

HTTP requests sent to your registered payload urls will contain several special headers:

API Endpoints

You can manage webhooks from the public api. This is particularly useful if you wish your integration to automatically manage subscriptions on behalf of authorized user.

List Subscriptions

Returns a list of webhook subscriptions for the current user.

GET /api/v0/webhooks/subscriptions.{json|yml|xml}

Sample Response

{
  "meta": {
    "message": "Everything executed as expected.",
    "more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#ok",
    "status": "ok"
  },
  "response": {
    "subscriptions": [
      {
        "trigger_table": "task",
        "trigger_type": "update",
        "subscription_id": "583e3c6328dc591a33139361",
        "content_type": "application/x-www-form-urlencoded",
        "trigger_url": "https://your-domain.com/callback",
        "user_deployment": "your-deployment",
        "user_id": 1,
        "event_id": "assign_task"
      }
    ],
    "subscriptions_users": [
      {
        "id": 1,
        "name": "Simon Jackson",
        "email": "simon.jackson@your-domain.com"
      }
    ]
  }
}

List Subscription Types

Returns an array of subscription events. Use this endpoint to grab a list of event ids.

GET /api/v0/webhooks/subscriptions/types.{json|yml|xml}

Sample Response

{
  "meta": {
    "message": "Everything executed as expected.",
    "more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#ok",
    "status": "ok"
  },
  "response": {
    "types": [
      {
        "trigger_table": "task",
        "event_title": "Task assigned",
        "event_id": "assign_task",
        "trigger_type": "update"
      },
      {
        "trigger_type": "update",
        "event_id": "unassign_task",
        "trigger_table": "task",
        "event_title": "Task unassigned"
      },
      {
        "event_title": "Quote created",
        "trigger_table": "quote",
        "event_id": "create_quote",
        "trigger_type": "create"
      },
      {
        "trigger_type": "create",
        "event_id": "create_request",
        "event_title": "Request created",
        "trigger_table": "request"
      },
      {
        "trigger_type": "update",
        "event_id": "update_request_status",
        "event_title": "Request status changed",
        "trigger_table": "request"
      }
    ]
  }
}