Loading... Background job is running.

Edit on GitHub

Notifications

Documentation

Features

Articles

Private Packagist Self-Hosted

Notification Types

Package Releases

Private Packagist will notify you every time a new or modified version is discovered in one of the selected packages, e.g. anytime a tag, branch or commit is created or modified in a VCS repository. You can specify which private packages you want to get notifications for and whether you want to receive notifications for mirrored packages. You can filter releases by stability: "dev / any" will match any release including commits to a branch, whereas "stable" will only match releases considered stable releases by Composer.

Abandoned Packages

Private Packagist will notify you as soon as a package in your Private Packagist organization gets marked as abandoned. You can specify which private packages you want to get notifications for and whether you want to receive notifications for mirrored packages.

Private packages will get marked as abandoned as soon as the abandoned property is set in the composer.json or for GitHub repositories as soon the repository has been archived. Third party mirrored repositories can also set the abandoned property in the composer.json and Private Packagist will automatically mark packages as abandoned if they get removed from the mirrored third party repository.

Security Alerts

Security Monitoring allows you to receive notifications when security issues are found in dependencies of selected projects.

Security Summaries

In addition to immediate security alerts you can also receive either weekly or monthly summaries listing all open security issues in dependencies of your organization's monitored projects.

Configuring Notifications

Every user receives security notifications by email for all projects they have access to by default. Users can unsubscribe either from individual projects or from all security notifications if they do not wish to receive email notifications.

Notification channels allow you to receive notifications via other means than email to user accounts. The following types of notification channels are available:

  • Email: Sends notifications to a list of email addresses
  • Slack Webhook: Sends notifications to your configured Slack channel
  • Microsoft Teams Webhook: Sends notifications to your configured Microsoft Teams channel
  • Webhook: Sends an HTTP POST request to a defined URL optionally signed with a user supplied secret.

Notification channels can be added on your organization’s settings page under Notification Channels -> Add Notification Channel.

Receiving Webhook Notifications

Webhook notifications are sent as HTTP POST requests to the endpoint configured with the notification event data send as payload. HTTP, server, and network errors will automatically be retried up to five times.

Delivery Headers

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:

Header Description
Packagist-Event Name of the notification event
Packagist-Notification Notification identifier, allows you to track a notification across multiple retries
Packagist-Delivery Identifier for the current request/delivery
Packagist-Signature Signature to validate the request based on the payload. This header will only be sent if a webhook secret is configured.

Webhook Request Validation

We recommend that you set up a webhook secret and validate the payload either using our api client or by running hash_equals('sha1='.hash_hmac('sha1', (string) $request->getBody(), $SECRET_USER_CHOSEN), $response->getHeader('Packagist-Signature'));

Webhook Example Payloads

Every webhook notification channel has a deliveries section which shows you the most recent notifications the channel received. You can also resend previous notifications.

Test Notification

Test notification to help you validate the setup of your webhook endpoint. You can send the notification by clicking on the "Trigger Test" button.

{
    "test": "Test notification"
}

Package Release Notification

Triggered every time Private Packagist finds one or more releases of a single package matching the criteria of the notification channel.

{
    "package": {
        "id": 1,
        "name": "acme/cool-lib",
        "origin": "private",
        "installable": true,
        "config": {
            "type": "vcs",
            "url": "https://github.com/acme/website",
            "customJson": null,
            "credentialsId": 432,
            "mirroredRepositoryId": 543,
            "artifactIds": [
                42
            ],
            "defaultSubrepositoryAccess": "no-access"
        },
        "credentials": 432,
        "abandoned": true,
        "replacementPackage": "acme/replacement-package",
        "links": {
            "self": "https://packagist.com/api/packages/acme/cool-lib",
            "webhook": "https://packagist.com/hooks/generic/999999/42PackageHash42",
            "webView": "https://packagist.com/orgs/myorg/packages/999999"
        }
    },
    "versions": [
        {
            "version": "1.0.0",
            "versionNormalized": "1.0.0.0",
            "sourceReference": "5df1797d20c6ab1eb606dc0f0d76a16ba57ddb7f",
            "distReference": "5df1797d20c6ab1eb606dc0f0d76a16ba57ddb7f",
            "releasedAt": "2022-08-08T16:21:43+00:00"
        }
    ]
}

Abandoned Package Notification

Triggered every time a package gets marked as abandoned.

{
    "package": {
        "id": 1,
        "name": "acme/cool-lib",
        "origin": "private",
        "installable": true,
        "config": {
            "type": "vcs",
            "url": "https://github.com/acme/website",
            "customJson": null,
            "credentialsId": 432,
            "mirroredRepositoryId": 543,
            "artifactIds": [
                42
            ],
            "defaultSubrepositoryAccess": "no-access"
        },
        "credentials": 432,
        "abandoned": true,
        "replacementPackage": "acme/replacement-package",
        "links": {
            "self": "https://packagist.com/api/packages/acme/cool-lib",
            "webhook": "https://packagist.com/hooks/generic/999999/42PackageHash42",
            "webView": "https://packagist.com/orgs/myorg/packages/999999"
        }
    }
}

Security Issue Notification

Triggered every time Private Packagist finds one or more security issues for a single project.

{
    "package": {
        "id": 1,
        "name": "acme/cool-lib",
        "origin": "private",
        "installable": true,
        "config": {
            "type": "vcs",
            "url": "https://github.com/acme/website",
            "customJson": null,
            "credentialsId": 432,
            "mirroredRepositoryId": 543,
            "artifactIds": [
                42
            ],
            "defaultSubrepositoryAccess": "no-access"
        },
        "credentials": 432,
        "abandoned": true,
        "replacementPackage": "acme/replacement-package",
        "links": {
            "self": "https://packagist.com/api/packages/acme/cool-lib",
            "webhook": "https://packagist.com/hooks/generic/999999/42PackageHash42",
            "webView": "https://packagist.com/orgs/myorg/packages/999999"
        }
    },
    "issues": [
        {
            "id": 42,
            "packageName": "monolog/monolog",
            "state": "open",
            "stateChangedAt": "2022-08-08T16:21:43+00:00",
            "stateChangedBy": "User X",
            "branch": "dev-master",
            "installedPackage": "acme/library",
            "installedVersion": "1.10",
            "advisory": {
                "advisoryId": "PKSA-abc1-def2-ghi3",
                "packageName": "acme/library",
                "remoteId": "acme/library/CVE-1999-99999.yaml",
                "title": "CVE-1999: Remote code execution",
                "link": "https://acme.website/security-advisories",
                "cve": "CVE-1999",
                "affectedVersions": ">=1.0",
                "source": "FriendsOfPHP/security-advisories",
                "sources": [
                    {
                        "name": "FriendsOfPHP/security-advisories",
                        "remoteId": "acme/library/CVE-1999-99999.yaml"
                    }
                ],
                "reportedAt": "2019-01-15T17:30:00Z",
                "composerRepository": "https://packagist.org"
            }
        }
    ]
}

Security Single Issue Notification

Triggered every time Private Packagist finds a security issue for a single project. If configured, this will be sent instead of the regular security issues webhook which aggregates issues found at the same time. This is useful if your target cannot parse object collections, e.g. Jira.

{
    "package": {
        "id": 1,
        "name": "acme/cool-lib",
        "origin": "private",
        "installable": true,
        "config": {
            "type": "vcs",
            "url": "https://github.com/acme/website",
            "customJson": null,
            "credentialsId": 432,
            "mirroredRepositoryId": 543,
            "artifactIds": [
                42
            ],
            "defaultSubrepositoryAccess": "no-access"
        },
        "credentials": 432,
        "abandoned": true,
        "replacementPackage": "acme/replacement-package",
        "links": {
            "self": "https://packagist.com/api/packages/acme/cool-lib",
            "webhook": "https://packagist.com/hooks/generic/999999/42PackageHash42",
            "webView": "https://packagist.com/orgs/myorg/packages/999999"
        }
    },
    "issue": {
        "id": 42,
        "packageName": "monolog/monolog",
        "state": "open",
        "stateChangedAt": "2022-08-08T16:21:43+00:00",
        "stateChangedBy": "User X",
        "branch": "dev-master",
        "installedPackage": "acme/library",
        "installedVersion": "1.10",
        "advisory": {
            "advisoryId": "PKSA-abc1-def2-ghi3",
            "packageName": "acme/library",
            "remoteId": "acme/library/CVE-1999-99999.yaml",
            "title": "CVE-1999: Remote code execution",
            "link": "https://acme.website/security-advisories",
            "cve": "CVE-1999",
            "affectedVersions": ">=1.0",
            "source": "FriendsOfPHP/security-advisories",
            "sources": [
                {
                    "name": "FriendsOfPHP/security-advisories",
                    "remoteId": "acme/library/CVE-1999-99999.yaml"
                }
            ],
            "reportedAt": "2019-01-15T17:30:00Z",
            "composerRepository": "https://packagist.org"
        }
    }
}

Security Summary Notification

A weekly or monthly summary notification containing all open security issues for all projects in your organization.

[
    {
        "package": {
            "id": 1,
            "name": "acme/cool-lib",
            "origin": "private",
            "installable": true,
            "config": {
                "type": "vcs",
                "url": "https://github.com/acme/website",
                "customJson": null,
                "credentialsId": 432,
                "mirroredRepositoryId": 543,
                "artifactIds": [
                    42
                ],
                "defaultSubrepositoryAccess": "no-access"
            },
            "credentials": 432,
            "abandoned": true,
            "replacementPackage": "acme/replacement-package",
            "links": {
                "self": "https://packagist.com/api/packages/acme/cool-lib",
                "webhook": "https://packagist.com/hooks/generic/999999/42PackageHash42",
                "webView": "https://packagist.com/orgs/myorg/packages/999999"
            }
        },
        "issues": [
            {
                "id": 42,
                "packageName": "monolog/monolog",
                "state": "open",
                "stateChangedAt": "2022-08-08T16:21:43+00:00",
                "stateChangedBy": "User X",
                "branch": "dev-master",
                "installedPackage": "acme/library",
                "installedVersion": "1.10",
                "advisory": {
                    "advisoryId": "PKSA-abc1-def2-ghi3",
                    "packageName": "acme/library",
                    "remoteId": "acme/library/CVE-1999-99999.yaml",
                    "title": "CVE-1999: Remote code execution",
                    "link": "https://acme.website/security-advisories",
                    "cve": "CVE-1999",
                    "affectedVersions": ">=1.0",
                    "source": "FriendsOfPHP/security-advisories",
                    "sources": [
                        {
                            "name": "FriendsOfPHP/security-advisories",
                            "remoteId": "acme/library/CVE-1999-99999.yaml"
                        }
                    ],
                    "reportedAt": "2019-01-15T17:30:00Z",
                    "composerRepository": "https://packagist.org"
                }
            }
        ]
    }
]

Articles

Features

Start Free Trial

Login to create an organization and start your free trial!