Skip to content

πŸ”· Laravel package for interacting with Jira Webhooks

License

Notifications You must be signed in to change notification settings

Stichoza/jira-webhooks-laravel

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

30 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Jira Webhooks Laravel

Latest Stable Version Total Downloads Downloads Month Petreon donation PayPal donation

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.

Note 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.