Webhooks allow for instant notifications to be sent to a registered URL. Each notification makes a HTTP Post call to your registered URL and passes information about the action that just occurred in your Teamwork account.

For this example, we'll be listening for the PROJECT.CREATED webhook event.

Step 1 - Enable Webhooks on your Teamwork account

Log in to your Teamwork account as an Administrator in the Owner Company.

Click Settings in the top right and choose Webhooks

Next make sure the toggle switch Webhook Enabled is turned on

Under the event section you need to choose PROJECT.CREATED and enter a URL on your server that will be called when the event happens in your Teamwork account.

This can be any URL using any server side language such as ColdFusion, PHP, JSP, ASP, Ruby etc

Step 2 - Write your server side page

The URL you entered in the Webhooks Settings Section needs to accept FORM posted variables and respond with a Status 200 in a timely fashion.

When Teamwork calls your URL, it passes 4 Form variables to your page:

  • accountId - The Teamwork Account Id
  • event - The event being notified (In this example it would be PROJECT.CREATED)
  • bbjectId - The ID of the item the event relates to. (In this example it would be the project that was just created)
  • userId - The ID of the user who performed the action (In this example it would be the user that just created the project)

Step 3 - Get information about the new project using the Teamwork API

To get the original project name you need to call the Teamwork API (http://developer.teamwork.com) with a valid API Token

The call you will need to make is GET /projects/{id}.json (Swap {id} with the objectid sent via the Webhooks call above)

This will give you a JSON representation of the specific project that was just created.

{ "project": { "company": { "name": "Digital Crew", "id": "47" }, "starred": true, "name": "Example project", "show-announcement": false, "announcement": "", "description": "", "status": "active", "created-on": "2014-01-15T11:58:09Z", "category": { "name": "", "id": "" }, "start-page": "projectoverview", "logo": "", "startDate": "", "notifyeveryone": false, "id": "967", "last-changed-on": "2014-01-29T16:10:16Z", "endDate": "" }, "STATUS": "OK" }
Get the name of the project from the returned JSON and store it as a variable so you have "Example Project"

Next, get the ID from the returned JSON. You can come up with your own naming convention but for this example I'm going to prepend the ID to the project name so we now have "[#967] Example Project"

Step 4 - Update the project with the new name using the Teamwork API

We now have our new project name which we want to update on our live Teamwork account.

To do this you need to make a call to PUT /projects/{id}.json (Swap {id} with the objectid sent via the Webhooks call above) sending the following JSON packet

{ "project": { "name": "[#967] Example project" } }
That's it! Every time a new project is created in your Teamwork account your script will be called and the project will be updated.

You can do this with all objects in Teamwork such as Milestones, Tasks, Notebooks etc