Webhooks – iceScrum

Documentation This documentation applies only to iceScrum v7.
For old iceScrum R6, read the documentation or migrate.

Contents


Webhooks allow external services to be automatically notified by an HTTP request when important events happen in iceScrum.

Principles

Webhooks allow you to integrate iceScrum with third party web applications by allowing them to subscribe to iceScrum events. When one of these events is triggered, an HTTP POST request containing a JSON payload is sent to the configured URL.

Webhooks allow you to build elaborate integrations and customize your iceScrum experience. You can use them in combination with the iceScrum REST API. Using Webhooks is a great alternative to “polling” data on a regular basis, achieving the same result with a greater efficiency in ressource usage while requiring less work on your side.

Create a Webhook

To create a Webhook on your project, enable the App. Then, open your project settings under the “Webhooks” section when logged in as a Product Owner or ScrumMaster.

Then, define your Webhook:

  • Webhook URL: this URL will receive your data when iceScrum events occur. Be careful, this may lead to a data breach if this URL is not secure.
  • Secret key (optional): when defined, this key is used to generate a signature that will allow the receiver to validate the payload.
  • SSL verification: by default, the SSL certificate of the Webhook URL are verified when delivering payloads. Disable verification only if you know what you are doing!
  • Events: either Story events, all the events (from stories, tasks, features, acceptance tests, sprints, comments…) or selected events.
  • Enable: events are sent to the Webhook URL only if the Webhook is enabled.

HTTP request

The HTTP POST request generated for the event contains HTTP headers and a payload.

The payload contains the full JSON object associated to the event, e.g. the Story, as you would get it through the corresponding REST API.

In addition to the payload, the request contains specific HTTP headers:

  • x-icescrum-event: code that identifies the event type, e.g. story.create, story.update…
  • x-icescrum-signature: provided only if a Secret key was configured. It is the hash-based message authentication code (HMAC) of the event. It is the result of the sha1 function applied to your Secret Key and the request payload. If the receiver knows the Secret key, then it can generate its own signature from the key and the received payload in order to check it against the signature provided in this header. This allow verifying that the content has not been altered.

If the HTTP requests fails 5 times in a row (the limit can be changed in the server administration) then the Webhook is automatically disabled in order to avoid generating too many errors.

Webhook list

You can define as many Webhooks as needed, and update or delete Webhooks at any time.

The “New Webhook” form is not the only way to create hooks. Indeed, they may be created through our REST API or through the use of other Apps (e.g. Zapier). Depending on where they come from, you may or may not have the ability to update them manually.

Previous << Agile KPIs
Next Forecast >>

Try it for free now
All you need for your Agile project management