How to use webhooks for Git, Mercurial, and SVN repositories

We are excited to announce that SourceForge now supports webhooks for all Git, Mercurial, and Subversion repositories!

What are WebHooks?

Webhooks are custom URLs that project admins specify for their repo so that, when a commit occurs on that repo, you are notified via that URL. The advantage of webhooks is that you can set up automatic interactions with 3rd-party services to run tests, generate documentation, notify a chat room of your commits, and much more.

How to configure a webhook

Configure a webhook in the Admin section of your project by clicking on Tools. That’s where you’ll find your repository’s Webhooks link. All you need to do is enter your webhook URL and you’re good to go!

Many services work with webhooks, particularly those that use the URL as a trigger including Read the Docs or any Jenkins instance, without relying on specific details in the POST body. Some services use a webhook POST payload to see details like the commit message, branch, or user. Our webhook’s POST payload is similar to that of GitHub, so many services (e.g. Slack, etc.) will work when you manually configure a GitHub integration and paste the URL into the SourceForge webhook configuration page. However, if a service doesn’t work, for SourceForge compatibility, just ask its admin to update that service’s webhook handling to support the Allura webhook format.

When creating a service to listen to SourceForge webhooks, refer to the Allura webhook documentation for detailed examples of POST payloads and instructions on validating a webhook signature.

POST payload sample

Here’s a quick example of the POST content for Git, to whet your appetite:

{
    "after": "a72ab8566ed1a81e485a8451868ee9364069ea6b", 
    "before": "27bc571ceb56beeda796e0069bfba84581f55770",
    "size": 1,
    "commits": [
      {
        "id": "a72ab8566ed1a81e485a8451868ee9364069ea6b", 
        "message": "Update README", 
        "added": [], 
        "copied": [], 
        "removed": [], 
        "modified": [
          "README.md"
        ], 
        "author": {
          "email": "jetmind@example.com", 
          "name": "Igor Bondarenko", 
          "username": "jetmind"
        }, 
        "committer": {
          "email": "jetmind@example.com", 
          "name": "Igor Bondarenko", 
          "username": "jetmind"
        }, 
        "timestamp": "2015-02-23T14:30:42Z", 
        "url": "http://sourceforge.net/p/test/git/ci/a72ab8566ed1a81e485a8451868ee9364069ea6b/"
      }
    ], 
    "ref": "refs/heads/master", 
    "repository": {
      "full_name": "/p/test/git/", 
      "name": "Git", 
      "url": "http://sourceforge.net/p/test/git/"
    }
}

We also offer a Webhook management API to programmatically add, update, and remove webhooks. This is ideal if you’re creating an app or service and want to offer users a super-easy webhook configuration via an OAuth application and our webhooks APIs.

SourceForge runs on Apache Allura’s Open-Source Platform, which includes webhooks functionality.  You could contribute improved payloads, entirely new webhook events, and run your own internal project hosting site with the advanced features of Allura!

We hope you enjoy using webhooks at SourceForge!