PPM Express Help Center

What do you need help with?

Working with Webhooks in PPM Express

Webhooks are used to receive instant notifications about events happening in PPM Express as HTTP POST requests. 


Managing Webhooks

Please note: To create a Webhook, you need to have Administrate app permission in PPM Express. 

Webhooks are managed along with Public API via Swagger UI that is accessible from the Automation menu or any other API tool like Postman. To manage Webhooks, you need to generate a token from the Automation menu with any scopes.

Please note: You can create up to 50 webhooks per tenant. 


1. Create a Webhook:

To create a new webhook, make a POST request to 

host/@tenant-name/api-version/Webhooks 

with the following body:

{
  "eventTypes": [
    "Project:Created",
    "Project:Updated",
    "Project:Deleted",
     "Idea:Created",
     "Idea:Updated",
     "Idea:Deleted",
     "Task:Created",
     "Task:Updated",
     "Task:Deleted",
     "KeyDate:Created",
     "KeyDate:Updated",
     "KeyDate:Deleted"
  ],
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer token_value"
    },
    {
      "name": "custom_header",
      "value": "header_value"
    }
  ],
  "httpVerb": "POST",
  "url": "https://example.com"
}

 

2. Retrieve the list of Webhooks:

To retrieve the list of all created webhooks, make a GET request to 

host/@tenant-name/api-version/Webhooks

To view data regarding one specific webhook, please use this URL instead: 

host/@tenant-name/api-version/Webhooks/{id}

 Example of the response body:

{
   "data": [
     {
      "id": "041e7f10-2ac7-4ba6-bfd7-12753c333507",
      "eventTypes": [
        "Project:Created"
      ],
      "headers": [
        {
          "name": "Authorization",
          "value": "Bearer token_value"
        }
      ],
      "httpVerb": "POST",
      "url": "https://example.com"
     }
   ]
}

 

3. Delete a Webhook:

To delete all created webhooks, make a DELETE request to 

host/@tenant-name/api-version/Webhooks

In case you wish to delete one specific webhook, please use this URL instead: 

host/@tenant-name/api-version/Webhooks/{id}


Available webhook events

  • "Project:Created",
  • "Project:Updated",
  • "Project:Deleted",
  • "Idea:Created",
  • "Idea:Updated",
  • "Idea:Deleted",
  • "Task:Created",
  • "Task:Updated",
  • "Task:Deleted",
  • "KeyDate:Created",
  • "KeyDate:Updated",
  • "KeyDate:Deleted"

Please note:

1. For Project:Update and Idea:Update event types, webhook will be triggered only in case of Details section fields update.

2. Webhook for Task event will be triggered only for internal PPM Express tasks. Creation, update, and deletion of external tasks will not trigger a webhook of this event type;

3. Webhook created for Key Date will be triggered for  Portfolio and Program along with Project ones;

4. Webhook created for Key Date will be triggered for external key dates along with internal ones;       

 

Webhook payload examples

"Project:Created":

"WebhookId":"b4475520-5537-4c17-ad46-fb60a59fc5d1",
   "MessageId":"6879a8fe-59e7-49c5-af91-fd9c3b4bfad8",
   "Data":{
      "Id":"a9211e5f-7565-4647-9ff8-a13952992398",
      "Attributes":{
         "Impact":0,
         "Risk":0,
         "Cost":0,
         "Revenue":0,
         "Efforts":0,
         "RisksStatus":-1,
         "IssuesStatus":-1,
         "ResourcesStatus":-1,
         "CostStatus":-1,
         "ScheduleStatus":-1,
         "Id":"a9211e5f-7565-4647-9ff8-a13952992398",
         "Name":"Artificial Intelligence",
         "ParentIdea":null,
         "Portfolio":[
            
         ],
         "Program":[
            
         ],
         "HighLevelScope":null,
         "Progress":2,
         "Number":0,
         "StartDate":"2021-12-01T12:00:00Z",
         "FinishDate":"2021-12-31T12:00:00Z",
         "Description":null,
         "Priority":3,
         "Score":0,
         "Manager":[
            {
               "Id":"d56ca5f1-6f8f-4aff-877e-db257b87ba6a",
               "FullName":"John Doe",
               "ImageId":null
            }
         ],
         "Stage":null,
         "OverallStatus":-1,
         "Budget":0,
         "CreatedDate":"2022-02-10T14:49:18.6905833Z",
         "LastModifiedDate":"2022-02-10T14:49:18.6905834Z",
         "AlignmentScore":0,
         "ReportedTime":0,
         "PlannedWork":0
      },
      "Initiator":{
         "UserId":"d56ca5f1-6f8f-4aff-877e-db257b87ba6b",
         "FullName":"Anna Doe",
         "LogonAccount":"anna.doe@company.com"
      },
      "TimeStamp":"2022-02-10T14:49:18.8781961Z"
   }
}


"Idea:Updated":

{
   "WebhookId":"059d4f57-ba17-4789-8721-d2f87af1a0fc",
   "MessageId":"e379774d-eecd-46db-883e-94fc88a87974",
   "Data":{
      "Id":"9e854862-1506-4c36-961f-85c44b5f2b8f",
      "Attributes":{
         "BusinessPriority":3,
         "ExpectedEfforts":1000,
         "ExpectedCost":1000,
         "Idea’s sponsor":{
            "Id":"16facc4a-8b00-4fc6-a873-6dfa72afff85",
            "FullName":"Brian Adams",
            "ImageId":null
         },
         "Cost":2,
         "Efforts":4,
         "Tags":[
            "#shelter"
         ],
         "Impact":0,
         "Risk":0,
         "Revenue":0,
         "Name":"Dog Shelter Charity",
         "Description":"Let's donate $1000 each month",
         "AlignmentScore":0,
         "Stage":1,
         "ChildProject":null,
         "Challenge":{
            "Id":"657d8042-006b-498b-a041-d77d3968bc3a",
            "Name":”Charity ideas"
         },
         "Submitter":{
            "Id":"2158fcf3-d93d-4436-bff5-869f1d686d61",
            "FullName":"Anna Doe",
            "ImageId":null
         },
         "Budget":0,
         "CreatedDate":"2022-02-21T13:30:39.241Z",
         "LastModifiedDate":"2022-02-21T13:30:39.241Z",
         "DiscussionUrl":null,
         "StartDate":"2022-02-01T12:00:00Z",
         "FinishDate":"2022-02-28T12:00:00Z"
      },
      "BeforeAttributes":{
         "BusinessPriority":3,
         "ExpectedEfforts":1000,
         "ExpectedCost":1000,
         "Idea’s sponsor":{
            "Id":"16facc4a-8b00-4fc6-a873-6dfa72afff85",
            "FullName":"Brian Adams",
            "ImageId":null
         },
         "Cost":2,
         "Efforts":4,
         "Tags":[
            "#shelter"
         ],
         "Impact":0,
         "Risk":0,
         "Revenue":0,
         "Name":"Dog Shelter Charity",
         "Description":"Let's donate $1000 each month",
         "AlignmentScore":0,
         "Stage":0,
         "ChildProject":null,
         "Challenge":{
            "Id":"657d8042-006b-498b-a041-d77d3968bc3a",
            "Name":"Charity ideas"
         },
         "Submitter":{
            "Id":"2158fcf3-d93d-4436-bff5-869f1d686d61",
            "FullName":"Anna Doe",
            "ImageId":null
         },
         "Budget":0,
         "CreatedDate":"2022-02-21T13:30:39.241Z",
         "LastModifiedDate":"2022-02-21T13:30:39.241Z",
         "DiscussionUrl":null,
         "StartDate":"2022-02-01T12:00:00Z",
         "FinishDate":"2022-02-28T12:00:00Z"
      },
      "Initiator":{
         "UserId":"2158fcf3-d93d-4436-bff5-869f1d686d61",
         "FullName":"Anna Doe",
         "LogonAccount":"anna.doe@company.com"
      },
      "TimeStamp":"2022-02-21T13:30:57.5164308Z"
   }
}


"KeyDate:Updated":

{
   "WebhookId":"2b9ecfc3-ec2c-4e33-8207-520b47aac4ef",
   "MessageId":"dfa73971-cebc-47e0-8997-d56ea3c9fe52",
   "Data":{
      "ParentEntityId":"28e92b4c-3b0c-4100-83c8-80231b62efcb",
      "ParentEntityType":"Project",
      "Id":"776ec637-0e72-402f-8bdf-9e5f60bfbd3b",
      "Attributes":{
         "ShowOnTimeline":true,
         "Name":"Release 1.0",
         "Type":0,
         "Date":"2022-02-13T12:00:00Z",
         "IsComplete":true,
         "Status":10,
         "Description":null,
         "AssignedTo":[
            
         ]
      },
      "BeforeAttributes":{
         "Name":"Release 1.0",
         "Type":0,
         "Date":"2022-02-13T12:00:00Z",
         "IsComplete":false,
         "Status":1,
         "Description":null,
         "AssignedTo":[
            
         ]
      },
      "Initiator":{
         "UserId":"2158fcf3-d93d-4436-bff5-869f1d686d61",
         "FullName":"Anna Doe",
         "LogonAccount":"anna.doe@company.com"
      },
      "TimeStamp":"2022-02-14T08:20:46.4767404Z"
   }
}


"Task:Deleted":

{
   "WebhookId":"dd3576d1-d705-4419-a248-73694074e373",
   "MessageId":"f22f95a9-6e83-449f-bc6f-84a76300275a",
   "Data":{
      "ParentEntityId":"28e92b4c-3b0c-4100-83c8-80231b62efcb",
      "ParentEntityType":"Project",
      "Id":"99cbbe21-58f5-4987-b0fc-2640009b779c",
      "Attributes":{
         "Group":{
            "Id":"50a1d504-1f0a-4b39-99a7-4344e0755346",
            "Name":"Backlog",
            "Color":"#6a6b6d"
         },
         "StartDate":"2022-02-14T12:00:00Z",
         "DueDate":"2022-02-24T12:00:00Z",
         "Duration":9,
         "Progress":50,
         "Status":0,
         "IsMilestone":false,
         "Priority":0,
         "Name":"Create a test environment"
      },
      "Initiator":{
         "UserId":"2158fcf3-d93d-4436-bff5-869f1d686d61",
         "FullName":"Anna Doe",
         "LogonAccount":"anna.doe@company.com"
      },
      "TimeStamp":"2022-02-14T08:19:07.6883595Z"
   }
}


Was this article helpful?

Table of contents

    Back To Top