From 55df87bcdea32e02372f56813c4850f766d4dfd5 Mon Sep 17 00:00:00 2001 From: Sudar Selva Ganesh M <117903686+ssganesh035@users.noreply.github.com> Date: Mon, 17 Mar 2025 00:00:24 +0530 Subject: [PATCH] Update webhooks.rst --- docs/webhooks.rst | 110 +++++++++++++++++++++++++--------------------- 1 file changed, 59 insertions(+), 51 deletions(-) diff --git a/docs/webhooks.rst b/docs/webhooks.rst index 84cbf43fd..65d0702a5 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -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: @@ -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`. @@ -49,20 +55,23 @@ 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: @@ -70,15 +79,9 @@ For more details, see the :ref:`cli_add_webhook` section. 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 @@ -96,6 +99,8 @@ 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: @@ -103,14 +108,15 @@ For more details, refer to the :ref:`rest_api_webhooks` section. 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. @@ -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 ` to - apply the webhook globally across all projects. + - Alternatively, define a :ref:`Global Webhook ` 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.