Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stichoza/jira-webhooks-laravel
🔷 Laravel package for interacting with Jira Webhooks
https://github.com/stichoza/jira-webhooks-laravel
atlassian events jira laravel webhook webhooks
Last synced: about 2 months ago
JSON representation
🔷 Laravel package for interacting with Jira Webhooks
- Host: GitHub
- URL: https://github.com/stichoza/jira-webhooks-laravel
- Owner: Stichoza
- License: mit
- Created: 2023-07-23T13:56:31.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-08-03T18:38:03.000Z (over 1 year ago)
- Last Synced: 2024-10-12T23:51:06.855Z (3 months ago)
- Topics: atlassian, events, jira, laravel, webhook, webhooks
- Language: PHP
- Homepage:
- Size: 46.9 KB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Jira Webhooks Laravel
=====================
[](https://packagist.org/packages/stichoza/jira-webhooks-laravel) [](https://packagist.org/packages/stichoza/jira-webhooks-laravel) [](https://packagist.org/packages/stichoza/jira-webhooks-laravel) [](https://www.patreon.com/stichoza) [](https://paypal.me/stichoza)
Laravel package for interacting with Jira Webhooks.
## Installation
Install this package via Composer:
```bash
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`
```php
Stichoza\JiraWebhooksLaravel\JiraWebhooksLaravelServiceProvider::class,
```
If you want to use facade for routes, add this to aliases in you `config/app.php`
```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:
```bash
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:
```php
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.
```php
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.
```php
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.
```php
'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](https://developer.atlassian.com/server/jira/platform/webhooks/#registering-events-for-a-webhook).
> **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](https://github.com/Stichoza/jira-webhooks-data) package.
## Example
```php
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.