Webhook FAQs

  1. What are webhooks?
  2. What data is sent in the push notification?
  3. How do webhooks work?
  4. What's the best way to secure my webhook?
  5. What could I use Webhooks for?
  6. Can Webhooks be paused and resumed?

  1. What are webhooks?

    Webhooks are a way for Teamwork Projects to push notifications of events to an external URL registered for your account.

    Instead of polling the Teamwork Projects API constantly looking for changes, Teamwork Projects will send a HTTP POST request with the event details any time an action is performed in your account.

  2. What data is sent in the push notification?

    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
      • MILESTONE.CREATED
      • TASK.CREATED
      • COMMENT.UPDATED
      • etc
    • ObjectID: The numeric ID of the object modified
    • UserId: The numeric ID of the user who performed the modification

    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

  3. How do webhooks work?

    The first thing you need to do is enable Webhooks in your Teamwork Projects Account.

    To enable Webhooks, click Settings in the top right of your Teamwork Projects account, click Site Settings and select the Webhooks tab.

    You can register a Webhook URL for each available event.

    Once the webhook URL is added for an event we will send a HTTP POST request to this URL when ever the registered event happens in your Teamwork Projects account.

    We will send this push notification immediately and expect to get a Status Code of 200 back from your script to tell us everything was received correctly.

    If we do not receive a Status 200 from your script we will try again in 5 minute increments for a maximum of 3 attempts.

  4. What's the best way to secure my webhook?

    We currently support either HTTP or HTTPS urls, so you can have security by using an SSL-enabled url. But keep in mind that your endpoint is going to be wide-open on the internet, and you might not want others to be able to submit random data to your systems.

    At this time, aside from trying to keep the URL private, our best suggestion is to simply include a secret key in the URL your provide and check that GET parameter in your scripts.

  5. What could I use Webhooks for?

    Let’s look at a hypothetical example;

    Say you want to send an email to all of your users when a new task is added. Enable Webhooks in your Teamwork Projects account Settings and point the Webhooks URL to a valid script running on your own server.

    Make sure this script accepts HTTP POST requests and look for the event TASK.NEW

    Use the Teamwork Projects API to make a GET request to:

    GET /tasks/{objectId}.json

    This will query your Teamwork Projects account and get the details of the task that was just added. You can then send an email using your own server to the users you want to be notified.

    You could use the Webhooks to extend Teamwork Projects for your own needs that we do not yet cater for.

  6. Can Webhooks be paused and resumed?

    Yes. In the Settings section of your Teamwork Projects account under the Webhooks section you can pause/resume any registered webhooks.

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