Page Comparison

Warning

title	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.

Table of Contents

maxLevel	3
outline	true
style	circle

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

...

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.

...

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

Header	Description
X-Accelo-Event	ID of the

even

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.

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

Sample Response

Code Block

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

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

Sample Response

Code Block

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

Code Block
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

Code Block

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

Code Block

title	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.

Code Block
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.

Code Block
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.

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

Sample Response

Code Block
{ "status": 200 }

Version	Old Version 1	New Version Current
Changes made by	Kurt Wagner (Unlicensed)	Kurt Wagner (Unlicensed)
Saved on	Nov 30, 2016	Feb 09, 2017

Versions Compared

Key

Access

Limitations

Events

Payloads

Unsubscribe Status

Endpoints

List Subscriptions

Sample Response

List Subscription Types

Sample Response

Create Webhook Subscription

Parameters

Sample

Delete Webhook Subscription

Trigger Webhook Subscription

Dispatch Webhook Subscription

Sample Response