Setting up webhooks

Note: Webhooks are available on paid Teamwork.com subscription plans.

Within Teamwork.com, you can use webhooks to get data from actions that occur on your site such as tasks being created or milestones being edited.

Webhooks can be leveraged to achieve a variety of actions - some examples include:

Perform a specific action in a third-party app when a task is completed in Teamwork.com.
Extend the functionality of your Teamwork.com site (for example, send an email to a certain user when a task is created on your site).
Add a custom prefix to tasks when they are created in Teamwork.com.

Webhooks can be enabled and configured via the Webhooks section of your Teamwork.com site settings as well as via an individual project's settings.

Enabling Webhooks

Note: The site settings area is only accessible to owner company site administrators.

In the settings area, go to the Webhooks subsection where you will see an option to enable webhooks. Click the toggle to activate webhooks for your Teamwork.com site.

To enable Webhooks via our API, check out our Webhook endpoint here

Creating Webhooks at Site level

Note: If a webhook you are attempting to create at site level already matches an existing project webhook event and URL, you will be prompted to promote the existing webhook to site-level.

Once webhooks have been enabled for your site, you can go to the Registered Events subsection of the site settings and click Add Webhook to create a new one:

To create a Site level Webhook via our API, check out our Webhook endpoint here.

Creating Webhooks at Project level

Note: The project settings area is accessible to project administrators and above.

Once webhooks have been enabled for your site, you will see an additional Webhooks section in each project's settings area.

Click the Add Project Webhook button in the Registered Events subsection to create a new webhook for the project:

To create a Project level Webhook via our API, check out our Webhook endpoint here.

Tokens and Checksums on Version 2

The token field in your webhooks setup allows you to implement an additional security feature for your webhook consumer. We use the specified token to calculate a HMAC sha256 checksum of the 'body' of the HTTP POST and send it in the X-Projects-Signature header. You can use the same token to generate a checksum of the data on your end and compare the two checksums. You can find many examples online how to calculate this checksum, but here's our implementation in Go:

Function to calculate checksum

func generateSignature(data string, token string) (string, error) {
    sig := hmac.New(sha256.New, []byte(token))
    if _, err := sig.Write([]byte(data)); err != nil {
        return "", err
    }
    return hex.EncodeToString(sig.Sum(nil)), nil
}

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.