/
Webhooks

Webhooks

A webhook in Webhooks Pro is one outbound integration: a URL that receives JSON when configured Jira events happen, when a CRON schedule fires, or when a workflow transition runs the Trigger Webhook post function.

When to use it

Create a webhook whenever you need to push Jira changes out of Jira automatically:

  • An external service should react to issue creates / updates / comments / transitions.

  • You're bridging Jira to chat, paging, ticketing, CI/CD, or a data warehouse.

  • You need a periodic JQL snapshot delivered somewhere on a schedule.

If you only need one URL receiving everything, Jira's built-in webhooks are simpler. Reach for Webhooks Pro when you need any of: filtering, payload shaping, scheduling, signing, retries, or a delivery log.

How it works

How-it-works.png

 

For each enabled webhook, Webhooks Pro:

  1. Subscribes to the Jira events you tick on the Events tab.

  2. (Issue events only) runs the JQL filter if set — non-matching events are dropped.

  3. Holds the event for the debounce window so a burst of edits to the same entity collapses into one delivery.

  4. Renders the payload template against the event context.

  5. Sends the request to the configured URL with your headers and (optional) HMAC signature.

  6. Logs the full request, response, and timing — replayable from Webhook Logs.

A webhook can fire from up to three sources: Jira events, a CRON schedule, or a workflow post function. They use the same URL, headers, payload template, and signing settings.

Configure

The Webhooks page has two surfaces: the list (every webhook on this Jira) and the create / edit form.

From the list page

  • Create webhook (top right) — opens an empty form.

  • Click a row's name or its pencil icon — edit.

  • Status toggle — enable / disable in place.

  • Clone icon — duplicate as inactive (Copy).

  • ⋯ → Delete — removes the webhook and all related data (events, headers, query params, transition bindings, delivery logs).

  • Export (next to Create) — downloads a JSON bundle of every webhook plus the payload templates they use, ready for re-import on another tenant.

Filters on the list: name/URL search, status, event group, page size.

In the create / edit form

Section

What you set

Sub-page

Section

What you set

Sub-page

General

Name, Active, Description

(this page)

URL

Method, URL, payload template, headers, query params

(this page)

Security

HMAC signing secret

HMAC signing and secrets

Events

Which Jira events fire the webhook + JQL filter

Events and event families · JQL filtering

Schedule

CRON-driven periodic delivery

Scheduled webhooks

Transitions

Workflow transitions wired via post function (read-only here)

Trigger Webhook post function

{{ … }} placeholders in URL, headers, and query params

The URL, every header (key and value), and every query parameter (key and value) accept the same {{ … }} syntax used by Custom JSON payload templates — same root context (event, issue, project, entity, baseUrl, timestamp), same formatters (:number(…), :date(…), :json, :string).

URL https://api.example.com/issues/{{issue.key}}/events URL https://api.example.com/p/{{issue.project.key}} Header X-Issue-Key = "{{issue.key}}" Header X-Event = "{{event}}" Query project = "{{issue.project.key}}" Query date = "{{timestamp:date(yyyy-MM-dd)}}"

Substituted values in the URL are URL-encoded automatically; literal characters (:, /, ?, =, #) stay as written.

Don't put secrets in placeholders. A static Authorization token belongs in a literal header value — not pulled from an issue field. Anything resolved from Jira data ends up in the delivery log.

Save behaviour

  • Save is in the top right. Keyboard: Ctrl+S / ⌘S.

  • The first save to a new destination host triggers a Forge egress approval dialog for the Jira admin. See Approve egress to your endpoint.

  • After save, existing event subscriptions pick up the new webhook with no restart.

Send Test (edit mode only)

Fires a one-off delivery using a synthetic issue payload. Useful for validating the receiver without making a real Jira change. The HTTP status and round-trip time appear right in the form.

Examples

Minimum: send every issue create/update to one URL

 

 

 

 

Method

POST

URL

https://hooks.example.com/jira

Payload template

Default

Events

Issue created, Issue updated

JQL

(none)

Per-project URL via a placeholder

 

 

 

 

Method

POST

URL

https://hooks.example.com/jira/{{issue.project.key}}

Payload template

Default

Events

Issue updated

JQL

project in (ACME, BETA)

Signed delivery with a custom header

 

 

 

 

Header

X-Source: webhooks-pro

Security → Signing secret

hunter2-rotate-me

Events

Comment created

The receiver verifies X-Webhook-Signature: sha256=<hex> against the same secret — see HMAC signing and secrets.

Limits and gotchas

  • At least one event required — the form will not save with zero ticked.

  • Auto-disable — too many consecutive failures flips the webhook to AUTO-DISABLED (red lozenge). Tune the threshold in Auto-disable thresholds, or re-enable manually after fixing the receiver — see Re-enable an auto-disabled webhook.

  • HTTP method GET sends no body — payload templates are still rendered for the URL/headers/query, but the body is empty. The HMAC signature, if enabled, is computed over the empty string.

  • Egress approval is per host, not per webhook — once the admin approves api.example.com, every webhook in this app can reach it.

  • You cannot retrieve a saved signing secret. Rotation is one-way. Keep your own copy in a vault. See HMAC signing and secrets.

  • Schedules are UTC. The form does not convert from your locale. See UTC semantics and the fire-window.

  • Workflow transition bindings are managed in Jira's workflow designer, not on this page. The Transitions section is read-only with deep links to the relevant transitions.

Sub-pages

Related