Setting up Webhooks

Webhooks can be configured in the Webhook section of your Teamwork Projects Site Settings.

First you must enabled Webhooks for your Teamwork Projects account.

You can then register a URL for each type of Event you'd like to receive notifications about.

Receiving a webhook

Configuring your server to receive a new webhook is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL. Remember, with webhooks, your server is the server receiving the request.

When an event occurs on your Teamwork Projects account a HTTP POST request is sent to the registered URL.

This request will contain a number of parameters in the FORM scope:

  • 'accountId': The ID of your Teamwork Projects account
  • 'event': The event triggered on your Teamwork Projects account
    • etc
  • 'objectId': The numeric ID of the object modified
  • 'userId': The numeric ID of the user who performed the modification
  • 'projectId': Some webhook events send back the project ID that the item was part of
    • (This usually is sent back when the main item is deleted which would result in a 404 from the API such as TIME.DELETED)

Using the data sent, you can then use the Teamwork Projects API to get further details on the object.

For Example:

GET /tasks/{objectId}.json

Responding to a webhook

To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. You need to response to the Webhook within 5 seconds.

Any other information you return in the request headers or request body will be ignored. Any response code outside of 200, including 3xx codes, will indicate to Teamwork Projects that you did not receive the webhook.

When a webhook is not received for whatever reason, Teamwork Projects will continue trying to send the webhook once every hour for a maximum of 3 attempts after which they will be discarded.

Webhooks will automatically be deactivated if three or more events get discarded (ie: A status code other than 200 was returned after 3 tries).