Skip to content

Improve Webhooks Documentation with Additional Context and API Testing Tools #1626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve Webhooks Documentation with Additional Context and API Testing Tools #1626

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 59 additions & 51 deletions docs/webhooks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,18 @@
Webhooks
========

Webhooks in ScanCode.io allow you to receive real-time notifications about project
pipeline execution events. This enables integration with external services, automation
systems, or monitoring tools.
Webhooks in ScanCode.io allow you to receive real-time notifications about project pipeline execution events. This enables seamless integration with external services, automation systems, or monitoring tools.

Once configured, a webhook sends an HTTP ``POST`` request to the specified target URL
whenever the defined conditions are met. The webhook payload can include a summary of
the scan results or full pipeline execution details.
Once configured, a webhook sends an HTTP ``POST`` request to the specified target URL whenever the defined conditions are met. The webhook payload can include a summary of the scan results or full pipeline execution details, depending on your configuration.

ScanCode.io provides multiple ways to manage webhooks, including:
ScanCode.io provides multiple ways to manage webhooks:

- A **Web UI** for adding, modifying, and deleting webhooks.
- A **CLI command** for adding webhooks to projects from the command line.
- A **REST API** to configure webhooks programmatically.
- A **global setting** to automatically apply a webhook to every new project.
- **Web UI**: Add, modify, and delete webhooks using a graphical interface.
- **CLI command**: Configure webhooks from the command line for automation.
- **REST API**: Programmatically manage webhooks.
- **Global settings**: Apply a webhook automatically to every new project.

To test webhook delivery before integrating with production systems, you can use tools like **Beeceptor** (https://beeceptor.com/) or **PostBin** (https://www.postb.in/). These services allow you to inspect incoming webhook requests and debug payloads easily.

.. _webhooks_ui:

Expand All @@ -28,19 +26,27 @@ The ScanCode.io Web UI provides an interface to manage webhooks at the project l
From the **Project Settings** page, you can:

- **Create a webhook** by specifying a target URL that will receive notifications.
- **Modify an existing webhook** to change its target URL, trigger settings, or payload
details.
- **Modify an existing webhook** to change its target URL, trigger settings, or payload details.
- **Remove a webhook** if it is no longer needed.

### Webhook Configuration Options

When creating a webhook, the following options are available:

- **Target URL**: The destination URL where the webhook payload is sent.
- **Trigger on Each Run**: Choose whether to send notifications after every pipeline
run or only when all runs are complete.
- **Include Summary**: Include a high-level summary of the pipeline execution in the
webhook payload.
- **Include Results**: Optionally include the full scan results in the payload.
- **Active Status**: Enable or disable the webhook without deleting it.
+----------------------+---------------------------------------------------------------+
| **Option** | **Description** |
+======================+===============================================================+
| **Target URL** | The destination URL where the webhook payload is sent. |
+----------------------+---------------------------------------------------------------+
| **Trigger on Each | Send notifications after every pipeline run or only on |
| Run** | completion. |
+----------------------+---------------------------------------------------------------+
| **Include Summary** | Attach a high-level summary of the pipeline execution. |
+----------------------+---------------------------------------------------------------+
| **Include Results** | Optionally include full scan results in the payload. |
+----------------------+---------------------------------------------------------------+
| **Active Status** | Enable or disable the webhook without deleting it. |
+----------------------+---------------------------------------------------------------+

For details on how to access the Web UI, see the :ref:`user_interface_manage_webhook`.

Expand All @@ -49,36 +55,33 @@ For details on how to access the Web UI, see the :ref:`user_interface_manage_web
Managing Webhooks via the CLI
-----------------------------

Webhooks can also be managed from the command line using the ``scanpipe add-webhook``
command.
You can manage webhooks from the command line using the ``scanpipe add-webhook`` command.

Basic usage::
#### Basic Usage:

.. code-block:: bash

$ scanpipe add-webhook --project PROJECT TARGET_URL

Options include:
#### Available Options:

- ``--trigger-on-each-run``: Trigger the webhook after each pipeline run.
- ``--include-summary``: Include summary data in the webhook payload.
- ``--include-results``: Include detailed scan results.
- ``--inactive``: Create the webhook but leave it disabled.

To test the webhook delivery, you can use Beeceptor or PostBin before pointing it to your production system.

For more details, see the :ref:`cli_add_webhook` section.

.. _webhooks_api:

Managing Webhooks via the REST API
----------------------------------

The ScanCode.io REST API allows webhooks to be configured programmatically when
creating or updating a project.
The ScanCode.io REST API allows webhooks to be configured programmatically when creating or updating a project.

You can provide:

- A **single webhook URL** using the ``webhook_url`` field.
- A **list of webhook configurations** using the ``webhooks`` field.

Example JSON payload when creating a project:
### Example JSON payload when creating a project:

.. code-block:: json

Expand All @@ -96,21 +99,24 @@ Example JSON payload when creating a project:
]
}

To test the API configuration, you can use tools like **Beeceptor** or **PostBin** to inspect the incoming webhook requests.

For more details, refer to the :ref:`rest_api_webhooks` section.

.. _webhooks_global_setting:

Global Webhook Configuration
----------------------------

A **global webhook** can be automatically applied to every new project using the
``SCANCODEIO_GLOBAL_WEBHOOK`` setting.
A **global webhook** can be automatically applied to every new project using the ``SCANCODEIO_GLOBAL_WEBHOOK`` setting.

To enable this, add the following configuration in your ``.env`` file::
#### Configuration in ``.env`` file:

.. code-block:: ini

SCANCODEIO_GLOBAL_WEBHOOK=target_url=https://webhook.url,trigger_on_each_run=False,include_summary=True,include_results=False

Available options:
#### Available Options:

- ``target_url`` (**required**): The webhook destination URL.
- ``trigger_on_each_run`` (**default**: ``False``): Whether to trigger on every pipeline run.
Expand All @@ -124,28 +130,30 @@ For more information, see the :ref:`scancodeio_settings_global_webhook` section.
Slack Notifications
-------------------

The Webhook system in ScanCode.io provides built-in support for sending Slack
notifications using Slack's "Incoming Webhooks" feature.
ScanCode.io supports sending notifications to Slack using Slack's "Incoming Webhooks" feature.

If you want to receive notifications in Slack when your project's pipeline completes,
follow these steps:
### Steps to Integrate Slack Notifications:

1. **Create a Slack Incoming Webhook:**
Visit the Slack API documentation at https://api.slack.com/messaging/webhooks
to generate a webhook URL. The URL will be in the format:
``https://hooks.slack.com/...``.
- Visit the Slack API documentation at https://api.slack.com/messaging/webhooks.
- Generate a webhook URL (e.g., ``https://hooks.slack.com/...``).

2. **Configure a Webhook in ScanCode.io:**

- Add a webhook to your project using the Slack webhook URL as the target.
- Alternatively, define a :ref:`Global Webhook <webhooks_global_setting>` to
apply the webhook globally across all projects.
- Alternatively, define a :ref:`Global Webhook <webhooks_global_setting>` to apply the webhook globally.

3. **Ensure the Site URL is set:**
Make sure the :ref:`scancodeio_settings_site_url` setting is correctly defined in
your ``.env`` file::
- Define the site URL in your ``.env`` file:

.. code-block:: ini

SCANCODEIO_SITE_URL=https://scancode.example.com/

With these settings in place, ScanCode.io will send pipeline completion updates directly to your Slack channel.

## Testing Webhooks

SCANCODEIO_SITE_URL=https://scancode.example.com/
Before integrating with production services, test webhook responses using **Beeceptor** or **PostBin**:

With these settings in place, ScanCode.io will send pipeline completion updates directly
to your Slack channel.
- **Beeceptor**: Create an endpoint at https://beeceptor.com/, configure it as your webhook URL, and inspect incoming requests.
- **PostBin**: Set up a test endpoint at https://www.postb.in/ to monitor webhook payloads.
Loading