Open Beta

Webhooks are in open beta. The events are limited and subject to change. Please don't hesitate to provide feedback or suggestions. If there are events that would be most useful to you, please reach out to us.

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:

Event ID	Description
assign_task	Any time a task assignee changes. This includes going from assigned to unassigned.
~~unassign_task~~	~~Any time a task is unassigned.~~
create_quote	Any time a new quote is created.
create_request	Any time a new request is created.
update_request_status	Any time a request status changes.
create_invoice_pdf	Any time a PDF resource is generated.

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:

Header	Description
X-Accelo-Event	ID of the event that triggered the delivery. For example, "assign_task"
X-Hub-Signature	HMAC hex digest of the payload using your configured subscriptions secret.

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

name	description
trigger_url	URL we will trigger a HTTP POST to upon firing the registered event. For example, "https://your-domain.com/callback".
event_id	Unique event identifier. You can grab a list of possible subscription events from the get subscription types endpoint.
content_type	Content-type we will HTTP POST to your trigger URL. This can be either "application/x-www-form-urlencoded" or "application/json"
secret	Optional secret that we will use to generate a HMAC hex digest of the payload. The digest will be included in the triggered requests "X-Hub-Signature" header.

Underline indicates required.

Sample

Request

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

Response (201)

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