Jira Webhooks Laravel

Laravel package for interacting with Jira Webhooks.

Installation

Install this package via Composer:

composer require stichoza/jira-webhooks-laravel

This package uses Laravel's package auto-discovery, so you don't have to manually add the service provider.

Laravel Without Auto-discovery

If you don't use auto-discovery, add the ServiceProvider to the providers array in config/app.php

Stichoza\JiraWebhooksLaravel\JiraWebhooksLaravelServiceProvider::class,

If you want to use facade for routes, add this to aliases in you config/app.php

'JiraWebhooks' => Stichoza\JiraWebhooksLaravel\JiraWebhooks::class,

Export Configuration Files

(Optional) If you want to customize events dispatched by the package, copy the package config to your local config with the publish command:

php artisan vendor:publish --provider="Stichoza\JiraWebhooksLaravel\JiraWebhooksLaravelServiceProvider" --tag=config

Add Webhook Route

You can add webhook route to your routes file using JiraWebhooks class:

JiraWebhooks::route();

This will create a POST route with URI jira-webhook. You can also customize the URI of the route by passing a parameter. This method returns Illuminate\Routing\Route object, so you can use all other methods available on regular routes.

JiraWebhooks::route('jira/my_webhook')->middleware(SomeMiddleware::class);

CSRF Protection

If you're adding the route to your web routes, make sure you disable the CSRF middleware for the webhook route. Do this by adding URI to $except property of VerifyCsrfToken middleware.

protected $except = [
    // ...
    'jira-webhook', // or the custom URI you passed to `JiraWebhooks::route()`
];

Usage

By default, the package will dispatch Stichoza\JiraWebhooksLaravel\Events\JiraWebhookReceived event for any incoming webhook along with a specific event depending on the webhookEvent of webhook received.

Using Events

Here is the table of Jira webhookEvent event names and respective events dispatched by this package:

Jira event name	Event dispatched by this package
* (any webhook)	JiraWebhookReceived
jira:issue_created	JiraWebhookJiraIssueCreated
jira:issue_updated	JiraWebhookJiraIssueUpdated
jira:issue_deleted	JiraWebhookJiraIssueDeleted
jira:worklog_updated	JiraWebhookJiraWorklogUpdated
issuelink_created	JiraWebhookIssueLinkCreated
issuelink_deleted	JiraWebhookIssueLinkDeleted
worklog_created	JiraWebhookWorklogCreated
worklog_updated	JiraWebhookWorklogUpdated
worklog_deleted	JiraWebhookWorklogDeleted
comment_created	JiraWebhookCommentCreated
comment_updated	JiraWebhookCommentUpdated
comment_deleted	JiraWebhookCommentDeleted
project_created	JiraWebhookProjectCreated
project_updated	JiraWebhookProjectUpdated
project_deleted	JiraWebhookProjectDeleted
jira:version_released	JiraWebhookJiraVersionReleased
jira:version_unreleased	JiraWebhookJiraVersionUnreleased
jira:version_created	JiraWebhookJiraVersionCreated
jira:version_moved	JiraWebhookJiraVersionMoved
jira:version_updated	JiraWebhookJiraVersionUpdated
jira:version_deleted	JiraWebhookJiraVersionDeleted
user_created	JiraWebhookUserCreated
user_updated	JiraWebhookUserUpdated
user_deleted	JiraWebhookUserDeleted
option_voting_changed	JiraWebhookOptionVotingChanged
option_watching_changed	JiraWebhookOptionWatchingChanged
option_unassigned_issues_changed	JiraWebhookOptionUnassignedIssuesChanged
option_subtasks_changed	JiraWebhookOptionSubtasksChanged
option_attachments_changed	JiraWebhookOptionAttachmentsChanged
option_issuelinks_changed	JiraWebhookOptionIssueLinksChanged
option_timetracking_changed	JiraWebhookOptionTimeTrackingChanged
sprint_created	JiraWebhookSprintCreated
sprint_deleted	JiraWebhookSprintDeleted
sprint_updated	JiraWebhookSprintUpdated
sprint_started	JiraWebhookSprintStarted
sprint_closed	JiraWebhookSprintClosed
board_created	JiraWebhookBoardCreated
board_updated	JiraWebhookBoardUpdated
board_deleted	JiraWebhookBoardDeleted
board_configuration_changed	JiraWebhookBoardConfigurationChanged

Note

Default events are in Stichoza\JiraWebhooksLaravel\Events namespace.

Defining Custom Events

You can extend or customize event map by adding different events in config/jira-webhooks.php file. These are regular events that you can create by php artisan make:event command.

'events' => [
    // '*' => \Stichoza\JiraWebhooksLaravel\Events\JiraWebhookReceived::class,
    'jira:issue_created' => \App\Events\JiraIssueCreated::class,
    'jira:issue_updated' => \App\Events\JiraIssueUpdated::class,
    'comment_created' => \App\Events\JiraCommentCreated::class,
    'issuelink_*' => \App\Events\JiraIssueLinkCreatedOrDeleted::class,
    // ...
],

All events will receive the Stichoza\JiraWebhooksData\Models\JiraWebhookData object in the constructor.

The keys are checked against Jira's webhook event name (webhookEvent property) using Str::is() method, so you can use wildcards in names. You can find the full list of Jira webhook event names here.

Important

All events matching the pattern will be triggered, not just the first one.

Handling Events

You should define the listeners for the events that you configured in config/jira-webhooks.php file. You can create listeners using Laravel's php artisan make:listener command.

All events will have a webhook property of type Stichoza\JiraWebhooksData\Models\JiraWebhookData. This object contains all data from webhook request. Read more about these data structures in the readme of stichoza/jira-webhooks-data package.

Example

<?php

namespace App\Listeners;

use App\Events\JiraCommentCreated;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class JiraCommentCreatedListener implements ShouldQueue
{
    use InteractsWithQueue;

    public function handle(JiraCommentCreated $event): void
    {
        $title = 'New comment by ' . $event->webhook->comment->author->displayName
            . ' on issue ' . $event->webhook->issue->key;

        $message = $event->webhook->comment->author->displayName
            . ' said: ' . $event->webhook->comment->body;

        // Do something else
    }
}

Recommendations

It's recommended to make listeners queued. This package returns 200 OK response to Jira, so if the response will take too much time, Jira will assume that webhook delivery failed.