Webhook Integration

Agile Flights uses webhooks to automatically sync crate statuses from GitHub and JIRA. When you link a GitHub issue, pull request, or JIRA ticket as a crate, webhooks keep the crate status in sync with the external item - and can even auto-land flights when all crates are complete.

How It Works

When you link a GitHub issue/PR or JIRA ticket as a crate, webhooks keep the crate status in sync:

1. An external item changes status (e.g. a GitHub issue is closed)
2. GitHub/JIRA sends a webhook to Agile Flights
3. The crate status updates automatically (e.g. open to closed)
4. If all crates on a flight are complete, the flight auto-lands

GitHub Events

The following GitHub events are tracked:

• issues - opened, reopened, closed
• pull_request - opened, reopened, closed, merged
• projects_v2_item - status field changes (edited action only)

GitHub Project Crates

When a crate is linked to a GitHub Project (via the projects_v2_item event listed above), it behaves differently from issue or PR crates. Instead of a progress bar, the crate displays a completed-items counter - for example, "3 items completed".

This counter increments automatically via webhooks. Each time a project item is moved to a Done status, the projects_v2_item webhook fires and the count increases. No manual updates are needed.

Unlike issue and PR crates, GitHub Project crates are never auto-completed by the system. The Captain decides when the crate is done and marks it complete manually.

This is because GitHub's API does not expose a total item count through the token scope available to GitHub Apps. The system can track completed items incrementally via webhook events, but it cannot determine how many items exist in total - so it cannot calculate a completion percentage or trigger auto-completion. The Captain retains full control over when the crate is considered done.

JIRA Events

The following JIRA events are tracked:

• jira:issue_updated - status transitions (To Do → In Progress → Done)

Status Mapping

External statuses are mapped to crate statuses as follows:

Auto-Landing

When a crate status changes to completed, merged, or closed, the system checks whether the flight should auto-land:

1. Check if all crates on the flight are done
2. Check if the flight is in active or emergency status
3. If both conditions are met, the flight auto-lands

Flights in other statuses (e.g. takeoff, landed, archived) are not affected by auto-landing.

Setup

GitHub

GitHub is configured automatically when you install the Agile Flights GitHub App - no manual webhook setup required.

To connect GitHub:

1. Open your Agile Flights Dashboard
2. Go to Settings > Integrations
3. Click Connect GitHub and install the GitHub App
4. Select the repositories you want to grant access to

Once installed, webhooks are automatically configured for your repositories.

JIRA Configuration

Getting Your Webhook URL

Each organisation gets a unique, secure webhook URL. To find yours, go to Settings > Integrations and look at the connected JIRA card. If you are an organisation owner, you'll see a Webhook Setup section with a button to reveal your URL. Click Show Webhook URL and copy the full URL using the copy button.

The webhook URL contains a secret token unique to your organisation. Do not share it publicly - anyone with the URL could send fake status updates to your crates.

Configuring the Webhook

1. Go to your JIRA instance Settings > System > WebHooks
2. Click Create a WebHook and give it a name like "Agile Flights"
3. Paste the webhook URL you copied from the integrations page into the URL field
4. Under Events, check Issue > updated. This is the only event Agile Flights listens for - you can leave all other events unchecked.
5. Save the webhook

Once configured, any time a JIRA issue transitions to a "Done" status category (e.g. Done, Closed, Resolved), the linked crate in Agile Flights will automatically update to "completed". Transitions to other status categories will set the crate back to "open".

For general integration setup including connecting GitHub and JIRA to your organisation, see the Integrations page.