Scrumy API

Showing changes from revision #49 to #50: Added | Removed | Changed

Introduction

Webhooks are URLs that you specify to receive real time updates from your board. For example, when a task is moved, we will send a message to your webhooks that describes the change.

How do I set up a webhook?

You may have noticed that your settings now have a new section for webhooks. This is where you add URLs for where you want updates sent. However, before adding a webhook, you’ll have to set up an application at that url that will process the updates and properly respond to Scrumy.cavite homes settings now have a new section for webhooks. This is where you add URLs for where you want updates sent. However, before adding a webhook, you’ll have to set up an application at that url that will process the updates and properly respond to Scrumy.

Here are a few steps to get you started:

1. Set up an application at a globally accessible URL.
2. Ensure that any connection to that URL will return HTTP status code 200 (actually, anything under 400).
3. Go to the webooks portion of your settings, click the ‘add webhook’ link, and add your URL, such as cocktail dresses.
4. When you click the save button, some test data will be sent to your application. If the response is acceptable, the webhook will be enabled. If there are any errors, it will be saved, but disabled, and will not receive any updates.

What kinds of things will be sent to the webhook?

A webhook will get information about any task, story, or sprint that is created, updated, or deleted.

Create action

When a resource is created, a POST will be sent to the webhook with the following parameters:

• time: The time the resource was created in seconds since the epoch
• action: create
• resource: Will be one of task, story, sprint
• data: A JSON string representing the created resource

Update action

When a resource is updated, a POST will be sent to the webhook with the following parameters:

• time: The time the resource was created in seconds since the epoch
• action: update
• resource: Will be one of task, story, sprint
• id: The id of the resource being updated
• data: A JSON string representing the changes. This will be in the form of {field: [original value, new value]}

In addition to the standard updates, sprints and stories have special update actions for reordering of stories and tasks. In these cases, the POST will be like the following:

• time: The time the resource was created in seconds since the epoch
• action: order_tasks
• resource: story
• id: The id of the story whose tasks have been reordered
• data: A JSON string containing an array of task ids representing the order of the tasks.

Destroy action

When a resource is deleted, a POST will be sent to the webhook with the following parameters:

• time: The time the resource was created in seconds since the epoch
• action: destroy
• resource: Will be one of task, story, sprint
• id: The id of the deleted resource

What’s the easiest way to test webhooks?

The Scrumy Pro demo project is set up to allow 5 webhooks at a time, each one remaining active for no more than 5 minutes at a time. So, if you want to test your webhook without messing up your own project, feel free to add your webhook to an unused slot on the demo here;

A very simple script you can use to get a feel for the data pushed to a webhook would be the following Sinatra script:

require 'rubygems'
require 'sinatra'
post'/' do
  puts params.inspect
end

What happens if my webhook server goes down?

If there are any problems sending you a webhook (such as a refused connection, timeout, or an error response such as 500 or 404), it will retry 5 times in increasing intervals (the last attempt will be about 5 minutes after the first). If after 5 attempts it still cannot send the webhook, it will stop trying and you will receive an email with the data we tried to send, and the error that prevented success. If this happens more than 5 times without a successful hook, the webhook will be disabled until you manually enable it using the button on your settings.