Webhook Triggers

The Webhook Triggers app sends HTTP POST requests to external services when events occur in a YouTrack project. This app enables integrations with third-party systems, internal services, and automation pipelines.

Use this app to react to changes in issues, comments, work items, and attachments in near real time.

Use Cases

You can use the Webhook Triggers app to:

Trigger external workflows when issues change.
Synchronize YouTrack data with other systems.
Collect events for logging or auditing.
Integrate YouTrack with internal tools.

Supported Events

The app sends webhooks for the following event types.

Issue Events

Issue created
Issue updated
Issue deleted

Comment Events

Comment added
Comment updated
Comment deleted

Work Item Events

Work item added
Work item updated
Work item deleted

Attachment Events

Attachment added
Attachment deleted

Multiple and Catch-All Webhooks

For each event type, you can configure one or more webhook URLs.

Enter multiple URLs as a comma-separated or newline-separated list.
Catch-all webhooks receive all events regardless of type.

Catch-all webhooks are useful for centralized logging, auditing, or analytics.

Installation

The Webhook Triggers app is installed and managed through YouTrack administration.

Requirements

You must have administrative access to YouTrack.
You must have permission to manage apps for the assigned project.

Enable the App for a Project

Before webhooks can be configured in the app, the app first needs to be assigned to one or more YouTrack projects.

To enable the Webhook Triggers app for a project:

From the main navigation menu in YouTrack, select Administration > Apps.
Open Webhook Triggers.
Select the Projects tab and click Manage projects.
Select the target projects and click Save.

Configuration

The Webhook Triggers app can be configured after the app has been assigned to one or more YouTrack projects.

Generate a Webhook Token

Webhook requests are authenticated using a shared webhook token.

The minimum webhook token length is 32 characters.
A 64-character hexadecimal value is recommended.

openssl rand -hex 32

Store this value securely. The receiving service must use the same value to verify requests.

Configure Project Settings

Webhook URLs are an endpoint exposed by the external service (not YouTrack) that processes incoming HTTP POST requests. Find webhook URLs from the system that will receive the YouTrack events.

To configure the Webhook Triggers project settings:

From the main navigation menu, select Projects.
From the project list, select a project.
From the project navigation menu, select Apps.
Select the Webhook Triggers app and open the details sidebar and select the Settings tab.
- If the Webhook Triggers app is not available, it must first be added to the project. See Enable the App for a Project
Enter the webhook token created above. See Generate a Webhook Token
- This value is required and must be validated by the receiving service.
Enter an HTTP header name that carries the webhook token in outgoing requests.
- The header name is configurable (default X-YouTrack-Token). The receiving service must verify the header value.
For each supported event, specify one or more webhook URLs.
- URLs can be separated by commas or line breaks.
- Each configured URL receives a POST request when the event occurs.
Optionally, at the bottom of the app settings, configure webhook URLs that receive All Events.
- Use this option for centralized logging, auditing, or analytics.

Webhook Delivery

All webhooks are delivered as HTTP POST requests.

Method: POST
Content-Type: application/json
Authentication: shared webhook token in a request header

            Content-Type: application/json
            X-YouTrack-Token: <your-webhook-token>
        

The header name is configurable (default X-YouTrack-Token). The receiving service must verify the header value.

Webhook Payload Structure

All webhook payloads include a common base structure. Additional fields are included depending on the event type.

Base Payload

                {
                    "event": "eventType",
                    "timestamp": "2024-12-10T12:00:00.000Z",
                    "id": "2-123",
                    "numberInProject": 123,
                    "summary": "Issue title",
                    "project": {
                        "id": "project-id",
                        "name": "Project Name",
                        "shortName": "PROJECT"
                    }
                }
            

User Object

When a user is included, the payload contains the following fields.

                {
                    "id": "user-id",
                    "login": "username",
                    "fullName": "User Name",
                    "email": "user@example.com"
                }
            

Issue Created

                 {
                    "event": "issueCreated",
                    "timestamp": "2024-12-10T12:00:00.000Z",
                    "id": "2-123",
                    "numberInProject": 123,
                    "summary": "Issue title",
                    "project": { "id": "...", "name": "...", "shortName": "..." },
                    "description": "Issue description text",
                    "created": 1732708800000,
                    "reporter": { "login": "...", "fullName": "...", "email": "..." }
                 }
            

Issue Updated

When updated manually via the UI, each webhook typically contains one item in changedFields representing a single field change.

                {
                    "event": "issueUpdated",
                    "timestamp": "2024-12-10T12:00:00.000Z",
                    "id": "2-123",
                    "numberInProject": 123,
                    "summary": "Issue title",
                    "project": { "id": "...", "name": "...", "shortName": "..." },
                    "description": "Issue description text",
                    "updated": 1732708800000,
                    "updatedBy": { "id": "...", "login": "...", "fullName": "...", "email": "..." },
                    "changedFields": [
                        {
                            "name": "summary",
                            "oldValue": "Old title",
                            "value": "New title"
                        }
                    ]
                 }
            

Issue Deleted

                 {
                    "event": "issueDeleted",
                    "timestamp": "2024-12-10T12:00:00.000Z",
                    "id": "2-123",
                    "numberInProject": 123,
                    "summary": "Issue title",
                    "project": { "id": "...", "name": "...", "shortName": "..." },
                    "description": "Issue description text"
                 }
            

Comment Added / Updated / Deleted

Event types: commentAdded, commentUpdated, commentDeleted

                 {
                    "event": "commentAdded",
                    "timestamp": "2024-12-10T12:00:00.000Z",
                    "id": "2-123",
                    "numberInProject": 123,
                    "summary": "Issue title",
                    "project": { "id": "...", "name": "...", "shortName": "..." },
                    "comments": [
                        {
                            "id": "comment-id",
                            "text": "Full comment text",
                            "textPreview": "Comment preview...",
                            "created": 1732708800000,
                            "updated": 1732708800000,
                            "author": { "id": "...", "login": "...", "fullName": "...", "email": "..." }
                         }
                     ]
                 }
            

Work Item Added / Updated / Deleted

Event types: workItemAdded, workItemUpdated, workItemDeleted

                 {
                    "event": "workItemAdded",
                    "timestamp": "2024-12-10T12:00:00.000Z",
                    "id": "2-123",
                    "numberInProject": 123,
                    "summary": "Issue title",
                    "project": { "id": "...", "name": "...", "shortName": "..." },
                    "workItems": [
                        {
                            "id": "work-item-id",
                            "date": 1732708800000,
                            "duration": 3600000,
                            "description": "Work description",
                            "created": 1732708800000,
                            "updated": 1732708800000,
                            "author": { "id": "...", "login": "...", "fullName": "...", "email": "..." },
                            "type": { "id": "type-id", "name": "Development" }
                        }
                    ]
                }
            

Attachment Added / Deleted

Event types: issueAttachmentAdded, issueAttachmentDeleted

                {
                    "event": "issueAttachmentAdded",
                    "timestamp": "2024-12-10T12:00:00.000Z",
                    "id": "2-123",
                    "numberInProject": 123,
                    "summary": "Issue title",
                    "project": { "id": "...", "name": "...", "shortName": "..." },
                    "attachments": [
                        {
                            "name": "file.pdf",
                            "mimeType": "application/pdf",
                            "size": 12345,
                            "created": 1732708800000,
                            "author": { "id": "...", "login": "...", "fullName": "...", "email": "..." }
                        }
                    ]
                }
            

Security Considerations

Use HTTPS for all webhook URLs.
Keep tokens private and rotate them periodically.
Optionally restrict inbound traffic at the network level.

Troubleshooting

If you experience problems using the Webhook Triggers app, see if any of the following conditions apply.

Condition — 401/403 unauthorized or refused authentication error.

Cause	Solution
YouTrack is unable to authenticate because either the header name or the webhook token is incorrect.	Confirm the header name in your external service matches the header name sent by YouTrack. Confirm the webhook token matches exactly and contains no whitespace. Confirm the user supplying the permanent token has sufficient permissions to perform the requested operations.

Condition — A webhook is not triggering.

Cause	Solution
The webhook request is not sent when the configured event occurs in YouTrack.	Confirm that the webhook URL is entered into the Webhook Triggers app correctly. Confirm the event type is enabled and has at least one URL. Confirm that your external service is active and reachable from YouTrack.

Condition — Multiple webhook URLs are not firing.

Cause	Solution
One or more webhook URLs that have been entered in the Webhook Triggers app are incorrect or formatted incorrectly.	Confirm that all webhook URLs are entered into the Webhook Triggers app correctly. Separate by commas or new lines; verify no trailing spaces.

23 January 2026