Version 2

Version 2 webhooks, just like the original ones can be configured in the Webhooks section of your Teamwork Projects Site Settings.

  1. Enable Webhooks for your Teamwork Projects account.
  2. Click "Add Webhook"
  3. Select the event you require, paste in your URL, make sure Version 2 is selected
  4. You can configure different content-type, if you're used to working with our old webhooks - select Form
  5. You can enter a token which will be used to generate a checksum of the webhook payload
  6. Click "Add Webhook" to submit and you're done!

Receiving a webhook

Version 2 webhooks behave the same way as version 1 - we send a HTTP POST request to the specified URL.

However, the data sent is quite different as the payloads vary depending on the item and event. The good news is - we're sending quite a lot more data which means you most likely will not need to make any API calls following a webhook event. Please see our sample payloads to see what data to expect from our webhooks.

Just like with version 1 webhooks, to acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code, otherwise we'll assume that you did not receive it. Any information you return in the request headers or request body will be stored for a short period of time, you'll be able to view any previous deliveries and even redeliver them in the Webhooks section of your Site Settings when you click to edit any of the webhooks.

When a webhook is not received for whatever reason, Teamwork Projects will continue trying to send the webhook for another 3 attempts - after 1 minute, after 5 minutes and after 10 mintes. Afterwards, webhooks will give up on that specific delivery, however you can manually redeliver it in the Webhooks section of your site settings.


Content Type

To elaborate on Content Type selection - previously all version 1 webhooks were sent as Form data (application/x-www-form-urlencoded), which makes it easy to handle data in for a few platforms (PHP via $_POST, ColdFusion via FORM), however we'd like to provide more versatility and also offer XML and JSON as they're both common formats for APIs and third-party services.


Tokens and Checksums

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 sha256 checksum of the webhook payload 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
}


Comment on this page