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.

Limitations

We do not limit the amount of webhooks per deployment or user but we do enforce a 10 second timeout rule. If your trigger url takes more than 10 seconds to respond to webhook delivery, we will cancel the request. If this occurs too many times, we will delete your webhook subscription automatically.

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:

Unsubscribe Status

Your integration can tell Accelo to automatically unsubscribe by responding with a HTTP Status Gone 410. The dispatcher will respect this and instantly remove the subscription that caused the webhook trigger. Alternatively you can use the delete subscription endpoint mentioned below.

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"
      }
    ]
  }
}

Create Webhook Subscription

Creates and returns a new webhook subscription.

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

Parameters

Underline indicates required.

Sample

POST /api/v0/webhooks/subscriptions HTTP/1.1
Host: your-deployment.api.accelo.com
Content-Type: application/json

{
	"trigger_url": "https://your-domain.com/callback",
	"event_id": "assign_task"
}

{
  "meta": {
    "status": "ok_created",
    "more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#ok_created",
    "message": "A resource was successfully created."
  },
  "response": {
    "subscription": {
      "event_id": "assign_task",
      "user": {
        "email": "simon.jackson@accelo.com",
        "name": "Simon Jackson",
        "id": 1
      },
      "user_id": 1,
      "user_deployment": "hq",
      "trigger_url": "http://your-domain.com/callback",
      "content_type": "application/x-www-form-urlencoded",
      "subscription_id": "583f4b8028dc59073860a6d1",
      "trigger_type": "update",
      "trigger_table": "task"
    }
  }
}

Delete Webhook Subscription

Delete a given webhook subscription. Once this is done, you will no longer receive webhooks to the registered URL.

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

Trigger Webhook Subscription

Manually trigger a given subscription. This will queue the event to all other subscriptions and execute asynchronously. Use this if you want to trigger a subscription for an event for others, otherwise please see dispatch webhook subscription.

POST /api/v0/webhooks/subscriptions/{subscription_id}/trigger.{json|xml|yml}

Dispatch Webhook Subscription

Manually dispatch a given subscription synchronously. Unlike triggering, this will only execute the current subscription so other subscriptions of the event will not be affected. As it's synchronously you will get the HTTP status of the webhook result.

POST /api/v0/webhooks/subscriptions/{subscription_id}/dispatch.{json|xml|yml}

Sample Response

{
	"status": 200
}