Plan: Webhooks

Webhooks

Webhook deliveries are triggered when a card is created or when a card changes columns on the Plan board. To enable these deliveries, add an external URL to the input field on the Webhooks settings page. Once enabled, ossum will send an HTTP request containing a JSON payload to the specified endpoint.

To find the Webhooks Settings page, click the cog icon at the top right portion of the navigation bar.

Webhooks

Click into the "Accounts" tab within the horizontal navigation bar. Then, click on the account name for which you want to modify webhook settings.

Webhooks

Now, click into the "Webhooks" tab in the horizontal navigation bar. You should see an input that will accept an external URL to handle incoming webhooks from ossum.

Webhooks

Disabling/Enabling Webhooks

To disable/enable webhook deliveries, click the slide toggle to the left of the webhook url, then click the "Save" button.

Webhooks

The disabled state will appear gray with the slide toggle resting to the left, while the enabled state will appear orange with the slide toggle resting to the right.

WARNING

The webhook infrastructure within ossum is written to allow for up to 5 consecutive failed deliveries. Should there be 5 consecutive failed deliveries, the webhook will automatically be disabled.

Example Payload

{
  "events": [
    {
      "eventType": "AssetChanged",
      "webhookId": "demo-board-updates",
      "sequenceId": 26255,
      "timestamp": "2019-02-20T15:56:04.317Z",
      "targetAsset": {
        "_oid": "Story:7270:23816",
        "assetType": "Story",
        "href": "https://www11.v1host.com/Ossumdemo/story.mvc/Summary?oidToken=Story%3A7270%3A23816"
      },
      "changes": [
        {
          "name": "Status",
          "old": "StoryStatus:1011:1078",
          "new": "StoryStatus:7219:11468",
          "act": "Set"
        }
      ],
      "instigator": {
        "_oid": "Member:4159",
        "href": "https://www11.v1host.com/Ossumdemo/Member.mvc/Summary?oidToken=Member%3A4159",
        "name": "Alice Jones",
        "nickName": "Alice Jones",
        "email": "ajones@acme.com",
        "role": "Role:2",
        "roleName": "Project Admin",
        "avatar": "https://www11.v1host.com/Ossumdemo/Image.mvc/Show?imageOid=NULL"
      },
      "snapshot": {
        "_oid": "Story:7270:23816",
        "Number": "S-01060",
        "Name": "Allow invoices to be downloaded",
        "Status": {
          "_oid": "StoryStatus:7219:11468"
        },
        "Description": "Related to S-01048\n\nFrom list of payments allow the invoice to be downloaded",
        "Scope.Name": "demo",
        "Scope.Parent.Name": "demo.ROOT",
        "Owners": [
          {
            "_oid": "Member:4159:10313"
          }
        ],
        "Owners.Email": ["ajones@acme.com"],
        "TaggedWith": ["payments{amber}"]
      }
    }
  ],
  "baseUrl": "https://www11.v1host.com/Ossumdemo/"
}

TIP

There are a number of sites available for testing webhooks. You might first want to configure the URL to one of these sites so that you can easily see the JSON payload and HTTP headers before you create your own endpoint to receive the payload. These sites tend to change frequently so rather than link to a specific site would suggest a search for "webhook test site" to get a list of options.

 
Previous Article
Plan: Board Management

The columns on your board can be customized to suit your process. Only the Archived column is mandatory. Al...

Next Article
Code: Webhooks