Skip to main content

API

This section documents the public API for Phylum's artifact repository offering.

Webhooks​

Webhooks will send out notifications whenever a package that was accessed through a repository proxy fails analysis.

To setup a new webhook, you can use the following curl command:

# Phylum group used with the registry proxy.
export PHYLUM_GROUP=…
# https://docs.phylum.io/knowledge_base/api-keys#generate-an-api-key
export PHYLUM_API_KEY=…
# URL which will be called on analysis failure.
export WEBHOOK_URL=…
# Shared secret used to validate authenticity of webhook callbacks
export SECRET=…

curl \
    -X PUT \
    --user "$PHYLUM_GROUP:$PHYLUM_API_KEY" \
    --json "{\"url\": \"$WEBHOOK_URL\", \"secret\": \"$SECRET\"}" \
    "https://aviary.phylum.io/webhooks"

⚠️ WARNING ⚠️

Do not accidentally save your token into your shell history.

Once a webhook is registered, policy violations will be sent to it in the same format as the package check endpoint.

Since these reports contain security advisories, it's important to make sure that they were generated by Phylum and the endpoint wasn't called by a third party. To make this possible, all official webhook notification calls will include a sha256 query parameter which contains a hexadecimal representation of the SHA256-HMAC of the response body, generated with the shared secret provided when registering the webhook.

Deleting Webhooks​

If a webhook is no longer in use, it should be deleted:

# Phylum group used with the registry proxy.
export PHYLUM_GROUP=…
# https://docs.phylum.io/knowledge_base/api-keys#generate-an-api-key
export PHYLUM_API_KEY=…
# URL-encoded URL used during webhook setup.
export WEBHOOK_URL=…

curl \
    -X DELETE \
    --user "$PHYLUM_GROUP:$PHYLUM_API_KEY" \
    "https://aviary.phylum.io/webhooks/$WEBHOOK_URL"

⚠️ WARNING ⚠️

Do not accidentally save your token into your shell history.

Retrieving configured Webhooks​

To get a list with all configured webhook URLs for a group, you can send a GET request to the /webhooks endpoint:

# Phylum group used with the registry proxy.
export PHYLUM_GROUP=…
# https://docs.phylum.io/knowledge_base/api-keys#generate-an-api-key
export PHYLUM_API_KEY=…

curl \
    --user "$PHYLUM_GROUP:$PHYLUM_API_KEY" \
    "https://aviary.phylum.io/webhooks"

⚠️ WARNING ⚠️

Do not accidentally save your token into your shell history.