> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cysmiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound Webhooks

> Send workspace events to HTTPS endpoints for automation and monitoring.

## Overview

Outbound webhooks send real-time event notifications from Cysmiq to HTTPS endpoints you control.

<Info>Availability depends on your Cysmiq plan.</Info>

Use outbound webhooks to connect Cysmiq events to internal automation, ticketing workflows, SIEM pipelines, data warehouses, or notification systems.

## Create an endpoint

Select **New Endpoint** and configure:

| Field                   | What to enter                                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Description**         | Optional name for the endpoint. If blank, Cysmiq shows the endpoint URL.                                                              |
| **Payload URL**         | HTTPS URL that receives webhook deliveries. The URL cannot contain embedded credentials, URL fragments, or private network addresses. |
| **Scope**               | Workspace, organization, or repository scope for matching events.                                                                     |
| **Event Subscriptions** | One or more event labels or event groups that should trigger deliveries.                                                              |

After creating an endpoint, copy the **Signing Secret** immediately. Cysmiq only shows the signing secret when the endpoint is created or when the secret is rotated.

## Scope

| Scope                   | Events delivered                                   |
| ----------------------- | -------------------------------------------------- |
| **Workspace**           | Matching events from the entire workspace.         |
| **Organizational Unit** | Matching events tied to the selected organization. |
| **Repository**          | Matching events tied to the selected repository.   |

## Event Subscriptions

Select event labels to control which deliveries Cysmiq sends to an endpoint.

| Group           | Event label                  | Event name                     |
| --------------- | ---------------------------- | ------------------------------ |
| General         | All events                   | `*`                            |
| General         | Ping                         | `webhook.ping`                 |
| Scans           | All scan events              | `scan.*`                       |
| Scans           | Scan created                 | `scan.created`                 |
| Scans           | Scan completed               | `scan.completed`               |
| Scans           | Scan failed                  | `scan.failed`                  |
| Scans           | Scan aborted                 | `scan.aborted`                 |
| Scans           | Scan skipped                 | `scan.skipped`                 |
| Repositories    | Repository created           | `repository.created`           |
| Vulnerabilities | All vulnerability events     | `vulnerability.*`              |
| Vulnerabilities | Vulnerability created        | `vulnerability.created`        |
| Vulnerabilities | Vulnerability status changed | `vulnerability.status_changed` |
| Vulnerabilities | Vulnerability resolved       | `vulnerability.resolved`       |
| Vulnerabilities | Vulnerability closed         | `vulnerability.closed`         |
| Vulnerabilities | Vulnerability reopened       | `vulnerability.reopened`       |
| Vulnerabilities | Vulnerability regression     | `vulnerability.regression`     |

Selecting **All events** covers product events such as scan, repository, and vulnerability events. Use **Send Ping** from an endpoint's action menu to send a test **Ping** delivery directly to that endpoint.

Selecting **All scan events** covers every specific scan event. Selecting **All vulnerability events** covers every specific vulnerability event. Selecting **Vulnerability status changed** also matches the more specific vulnerability status events: **Vulnerability resolved**, **Vulnerability closed**, **Vulnerability reopened**, and **Vulnerability regression**.

## Endpoint Actions

Open an endpoint to manage it.

| Action            | What it does                                                            |
| ----------------- | ----------------------------------------------------------------------- |
| **Edit**          | Updates the description, payload URL, scope, or event subscriptions.    |
| **Send Ping**     | Sends a test **Ping** delivery to the active endpoint.                  |
| **Pause**         | Stops deliveries while keeping the endpoint configuration.              |
| **Resume**        | Starts deliveries again for a paused endpoint.                          |
| **Re-enable**     | Makes a disabled endpoint active again and resets consecutive failures. |
| **Rotate Secret** | Generates a new signing secret and shows it once.                       |
| **Delete**        | Permanently deletes the endpoint and its subscriptions.                 |

Endpoint statuses are **Active**, **Paused**, and **Disabled**. Cysmiq can disable an endpoint after repeated delivery failures. A `410 Gone` response also disables the endpoint.

## Signing

Cysmiq signs each webhook delivery with the endpoint signing secret. Store the secret in your receiving system and verify the signature before trusting the payload.

| Header                    | Purpose                                    |
| ------------------------- | ------------------------------------------ |
| `X-Cysmiq-Event`          | Event name, such as `scan.completed`.      |
| `X-Cysmiq-Event-Id`       | Event ID.                                  |
| `X-Cysmiq-Delivery-Id`    | Delivery ID.                               |
| `X-Cysmiq-Webhook-Id`     | Endpoint ID.                               |
| `X-Cysmiq-Attempt-Id`     | Delivery attempt ID.                       |
| `X-Cysmiq-Attempt`        | Attempt number for this delivery.          |
| `X-Cysmiq-Triggered-At`   | Timestamp when the delivery was triggered. |
| `X-Cysmiq-Schema-Version` | Payload schema version.                    |
| `X-Cysmiq-Signature`      | HMAC signature for the delivery body.      |

The signature header has the format `t=<unix_timestamp>,v1=<signature>`. During secret rotation overlap, the header can contain two `v1` signatures so receivers can accept the previous secret while switching to the new one.

To verify a delivery, compute an HMAC SHA-256 over `timestamp.delivery_id.attempt_id.raw_json_body` with the signing secret, then compare it with a `v1` value from `X-Cysmiq-Signature`.

## Payload

Webhook payloads use a JSON envelope.

| Field            | Meaning                                             |
| ---------------- | --------------------------------------------------- |
| `id`             | Event ID.                                           |
| `type`           | Event name.                                         |
| `created_at`     | When the event occurred.                            |
| `schema_version` | Payload schema version.                             |
| `mode`           | Payload mode. Current endpoints use `snapshot`.     |
| `workspace`      | Workspace ID and slug.                              |
| `data`           | Event-specific snapshot data.                       |
| `changes`        | Changed fields when the event includes change data. |

## Delivery History

Each endpoint shows recent deliveries with:

* **Event**
* **Status**
* **HTTP**
* **Attempts**
* **Triggered**

Open a delivery to inspect the payload, payload SHA-256, delivery metadata, and individual delivery attempts. Attempts include result, HTTP status, duration, start time, and error details when available.

Delivery statuses are:

| Status              | Meaning                                                                         |
| ------------------- | ------------------------------------------------------------------------------- |
| **Pending**         | Delivery is queued.                                                             |
| **Delivering**      | Cysmiq is sending the request.                                                  |
| **Retry Scheduled** | Delivery failed with a retryable result and will be retried.                    |
| **Succeeded**       | Receiver returned a successful response.                                        |
| **Failed**          | Delivery failed with a non-retryable result.                                    |
| **Exhausted**       | Retries were exhausted.                                                         |
| **Cancelled**       | Delivery was cancelled, usually because the endpoint cannot receive deliveries. |

## Redelivery

Use **Redeliver** from a terminal delivery detail view to queue a new delivery with the same payload. Redelivery is available only for terminal deliveries and only when the endpoint is active.

## Related Docs

* [Workspace security settings](/security-access/workspace-settings)
* [API keys](/security-access/api-keys)
* [Scans](/concepts/scans)
* [Vulnerabilities](/concepts/vulnerabilities)