Setting up Webhooks

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

Note: Webhooks are available on paid Teamwork subscription plans.

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.
  • Extend the functionality of your Teamwork 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.

Webhooks can be enabled and configured via the Webhooks section of your Teamwork 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 site.

webhookSetUp

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

Creating Webhooks at 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:

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.

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

Setting up Version 2 Webhooks

When creating your webhook using the steps above, make sure you select Version2 of the webhooks option. You can configure different content-type, if you’re used to working with our old webhooks - select Form.

Creating Webhooks at Project level

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

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

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:

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.