Integrations: webhooks and the read-only API

Ganttry connects to your other systems two ways: an outbound webhook that tells your system when something happens, and read-only API tokens that let your system read the company's projects whenever it likes. This page is written for the developer who builds the receiving side. Other named integrations appear on the card as Coming soon.

Where to find it#

A company admin opens the Company page › Integrations. The Integrations card has a Webhooks tile (showing Enabled or Off, with Configure…) and, below it, the company's API tokens with + New token….

Outbound webhooks#

Each company has one webhook: one payload URL. Configure… opens Webhook settings, with the Webhook URL, a Deliver events checkbox and Save. Ganttry sends each event to that URL as an HTTP POST with a JSON body (content-type: application/json).

• Use a public address. The URL must start with http:// or https:// and reach a public address. Private and local network addresses are refused when you save: "Enter a public webhook URL. This one points to a private or local network address."
• Give the final URL. Redirects are not followed — a 3xx answer counts as a failed delivery. Enter the receiver's own address, not one that forwards to it.
• Answer with a 2xx status to acknowledge a delivery.

The events#

The event names are the API's own and keep the word schedule; in the app, each one is a project.

The envelope#

Every delivery has the same outer shape:

• id — the event's own id;
• type — one of the four event names above;
• createdAt — when the event happened, as an ISO timestamp;
• companyId — your company;
• data — the event's details.

Delivery#

Delivery is best-effort. A failed delivery is retried once, 30 seconds later, and then the event is dropped. There is no queue to replay and no promise of order between events. Treat each event as a hint that something changed, and read the API (below) for the truth.

Read-only API tokens#

A token lets a system read the company's projects with plain GET requests.

• + New token… asks for a name (what will use it — for example Power BI), then shows the token once, in the API token created dialog. It starts with gtk_.
• A company can have up to 10 active tokens: "This company has 10 active API tokens. Revoke a token you no longer use before creating another."
• A token belongs to the company, not to the person who made it, so people joining or leaving never breaks an integration.
• The token list shows each token's name, when it was created, who created it and when it was last used, with Revoke.

Send the token in the Authorization header: Authorization: Bearer gtk_….

The endpoints#

The task rows come from a cache that is refreshed on each save. They include summary rows (unlike the app's own views), and a stale flag set to true when the dates may trail the project by a save.

Draft and Publish#

The API keeps answering while a project is held in Draft, and says so: each project in a response carries publicationHold and publishedRev, so your system can tell a held project from a live one. The API always returns the live project, not the plan last published to crews — see Draft and Publish.

For a screen in the field — a trailer TV or a kiosk tablet — you don't need a token: open a whole-project crew link on it instead (Crew links and itineraries). A crew link obeys the Draft hold the way a crew's own view does. The API has no link endpoint.

Limits and refusals#

• Requests are rate-limited per IP address. A request over the limit gets 429 with a Retry-After header.
• Anything that isn't a GET is refused.
• An unknown or revoked token reads as 404, the same as a wrong path — the API never confirms whether a token exists.

Keeping it secure#

• Check the signature on every delivery. Each delivery carries X-Ganttry-Signature: t=<unix time>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> keyed with your signing secret. This is Stripe's signature scheme, so any Stripe webhook-verification snippet works unchanged. Reject a delivery whose signature doesn't match.
• Keep the signing secret and every token in a password manager. Ganttry shows each one once — the signing secret when the webhook is first enabled (or when you press Replace signing secret), a token when it is created — and never again. Ganttry stores only a fingerprint of a token, so a lost token can't be shown again: revoke it and make a new one.
• A token reads everything. Every token reads every project in the company in full, costs included, whatever the role of the person who created it. Give one only to a system that should see all of that.
• Revoke a token the moment its system is retired. Revoke asks first — "Anything using it stops working immediately." — and it stops at once.
• Replacing the signing secret takes effect as you save: update the receiving system to the new secret straight away.

Who can use it#

Only a company Admin (and partner staff, for the companies their partner looks after) opens Integrations, sets the webhook and creates or revokes tokens. See Who can see and do what.

Good to know#

• Turning Deliver events off also cancels anything still waiting to be sent.
• The step-by-step version is Connect other tools.