XP-Dev.com Documentation

Webhooks

Webhooks are a very useful feature for your hosted projects and repositories. Once configured, our platform will call your webhook with a JSON object whenever there are project and repository changes.

Project Webhooks

Enabling for Projects

  • Head over to your XP-Dev.com project's Settings tab
  • Navigate to the Notifications sub-tab

Projects Settings Notification Tab

Under the Add a New External Notification form:

  • Select Webhook as the integration
  • Click on Add

Project Notification Add Form

  • Enter your webhook URL, which has to begin with http:// or https://
  • If your endpoint requires Basic Authentication, you can provide a username and password
  • Click on Save

Webhook Project Integration Add Form

Project Event JSON Object

Once configured, our platform will call your webhook for all project events with the following JSON object:

{
  "description": name of the artifact that has been changed (type: String, example: "Story #6"),
  "url": the url of the artifact (type: String, example: "https://account.xp-dev.com/story/4"),
  "eventType": how the artifact has been changed (type: Enum, one of: "created", "updated", "deleted"),
  "username": the user that created this event (type: String)
}

Disabling for Projects

  • Head over to your XP-Dev.com project's Settings tab
  • Navigate to the Notifications sub-tab
  • Click on Delete Notification next to your webhook integration

Webhook Project Integration Delete Form

Repository Webhooks

Enabling for Repositories

To enable webhooks on your repository:

  • Head over to your XP-Dev.com project's Repository tab
  • Click on the repository that you'd like to add a webhook to
  • Head to the Integrations sub-tab of your repository

Repository's Integration Tab

Under the Add a New Integration form:

  • Select Webhook as the integration
  • Click on Add

Repository Integration Add Form

  • Enter your webhook URL, which has to begin with http:// or https://
  • If your endpoint requires Basic Authentication, you can provide a username and password
  • Click on Save

Webook Integration Add Form

Repository Event JSON Object

Once configured, our platform will call your webhook for all repository push events with the following JSON object:

{
    "repository": { // object that describes the repository
        "name": name of the repository (type: String),
        "type": type of the repository (type: Enum, one of: Git, Mercurial, Subversion),
        "ssh_url": SSH url of the repository (type: String),
        "https_url": HTTPS url of the repository (type: String),
        "web_url": Url of the repository to view it with a browser (type: String)
    },
    "project": { // object that describes the project
        "name": name of the project (type: String)
        "web_url": Url of the project to view it with a browser (type: String)
    }
    "user": Username of the user that created the event (type: String),
    "reference": the branch or tag name, will be blank for Subversion repositories (type: String),
    "reference_type": Either a 'Branch' or 'Tag', omitted for Subversion repositories (type: Enum),
    "commits": [{ // array of objects that describe commits in this repository event
        "revision": the commit revision (type: String),
        "message": commit message (type: String),
        "timestamp": when the commit was created (type: ISO 8601 timestamp, eg: 2020-04-05T11:12:28.123Z),
        "url": Url of the commit to view it in a browser (type: String),
        "author": the commit author (type: String)
        "added": a list of file paths that were added in this commit (type: Array of Strings), 
        "removed": a list of file paths that were removed in this commit (type: Array of Strings), 
        "replaced": a list of file paths that were replaced in this commit (type: Array of Strings), 
        "modified": a list of file paths that were modified in this commit (type: Array of Strings) 
    }]
}

Disabling Webhooks for Repositories

  • Head over to your XP-Dev.com project's Repository tab
  • Click on the repository that has the webhook integration
  • Head to the Integrations sub-tab of your repository
  • Click on Delete Integration next to your webhook integration

Webhook Integration Dlete Form

Legacy pre-April 2020 Webhook Format

If your repository webhook integration was configured before April 2020, then it will receive our legacy JSON object for each commit:

{
    "repository": Name of the repository (Type:String),
    "message": Commit log message (Type:String),
    "timestamp": Timestamp of commit (Unix epoch in miliseconds) (Type:long),
    "author": Committer (Type:String),
    "revision": Commit revision (Type:long),        
    "reference": Commit branch or blank for Subversion (Type:String),        
    "repository_ssl_path": Full SSL URL to the repository root (Type:String),
    "repository_path": Full non-SSL URL to the repository root (Type:String),
    "revision_web": Url to view the changeset on XP-Dev.com (Type:String),
    "added": List of paths that have been added (Type:String array),
    "removed": List of paths that have been removed/deleted (Type:String array),
    "replaced": List of paths that have been replaced (Type:String array),
    "modified": List of paths that have been modifed (Type:String array)
}

An example of the JSON message is below:

{
    "message": "some changes for tomorrows release",
    "timestamp":1235327991226,
    "author":"rs",
    "revision":652,
    "reference":"refs/heads/master",
    "repository_ssl_path":"https://xp-dev.com/git/rs-importable/",
    "added":["/trunk/pyserver/something"],
    "revision_web":"https://xp-dev.com/sc/change/3/271dfc9d40480d706586bd8b44bf5b6ea9062d64",
    "repository":"rs-importable",
    "repository_path":"https://xp-dev.com/git/rs-importable/",
    "removed":["/trunk/pyserver/bootstrap/compile.py"],
    "replaced":[],
    "modified":["/trunk/pyserver/build.properties"]
}

Example Code to Receive the Data

PHP example:

<?php
    $json = file_get_contents('php://input');

    var_dump(json_decode($json));
?>

Feel free to contact us if you need any assistance.