Connect other tools with webhooks and the API

By the end of this workflow another system, such as a reporting dashboard or your accounting software, hears from Ganttry when a project is saved, published or finished, and can read your projects with a token.

Who does this#

A company Admin sets it up on the Company page, usually with the developer who will write the receiving side. This page is written for that developer too, and Integrations: webhooks and the read-only API documents every field, event and limit. See Who can see and do what.

Before you start#

• The receiving system has a public web address that accepts POST requests. Ganttry refuses private and local network addresses, and doesn't follow redirects, so use the receiver's final URL.
• A company has one webhook URL, and all four events go to it, so if several systems need them, have that one receiver pass them on.
• Decide where you will keep the signing secret and any API tokens. Ganttry shows each one once.

Steps#

Set up the webhook#

1. 1
   Open Integrations. Choose Company in the sidebar, then Integrations. The Webhooks tile works today; the other named tools are marked Coming soon.
2. 2
   Configure it. Press Configure… on the Webhooks tile. In Webhook settings, enter the Webhook URL, tick Deliver events and press Save.
3. 3
   Store the secret. The first time you turn delivery on, Ganttry makes a signing secret and shows it once, in Webhook signing secret. Copy it into your receiver's settings now.

4. 4
   Handle the events. Ganttry sends a JSON body shaped { id, type, createdAt, companyId, data } for four events:

   • schedule.saved: a project was saved, at most once a minute per project;
   • schedule.status_changed: its lifecycle status changed;
   • schedule.published: a plan was published to crews;
   • task.completed: tasks were marked done, one event per save listing them.
5. 5
   Verify every delivery. Each request carries X-Ganttry-Signature: t=<unix time>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> with your secret. It is the same scheme Stripe uses, so any Stripe webhook-verification code works. Reject a request whose signature doesn't match.

Make an API token#

6. 6
   Under the tiles, press + New token… and name it after what will use it, for example Power BI. API token created shows the token, starting gtk_, once. Store it now.
7. 7
   Send it with every request as Authorization: Bearer gtk_…. Three read-only endpoints answer:

   • GET /api/v1/schedules: the company's projects, with name, status, start date and task count;
   • GET /api/v1/schedules/:id: one project, with its whole schedule;
   • GET /api/v1/schedules/:id/tasks: one row per task, with dates, percent complete, status, crew and assignees.

8. 8
   Retire a token. Revoke on its row stops it at once, after a confirmation. Revoke any token whose system you no longer use.

Good to know#

• Treat events as hints. Delivery is best effort: a failed delivery is retried once after 30 seconds, then dropped. Read the API for the facts.
• Tokens belong to the company, not to a person, so staff changes never break an integration. A company holds up to 10.
• Read only. The API answers only GET requests and is rate-limited. An unknown or revoked token gets a 404, so the API never confirms whether a token exists.
• Drafts. The API always returns the project as last saved, even while it is in Draft; each response says whether the project is held and which version was published.
• A screen in the site trailer needs no token: open a whole-project crew link on it (see Send crews their links and itineraries).
• A new secret. Replace signing secret in Webhook settings makes a new one and saves the settings. Update your receiver straight away.