Set up Ticketing with a Webhook

Set up a webhook integration in a space to send the tickets users create in Mondoo to an HTTPS endpoint you run. Use it when Mondoo has no dedicated integration for your ticketing system, or when a service of your own, such as middleware that forwards tickets into an internal system, needs to receive them first.

For an overview of ticketing, read Track and Fix Findings with Ticketing.

Prerequisites

• Owner or Editor access to the Mondoo space

• An HTTPS endpoint that accepts POST requests with a JSON body and responds with a 2xx status code

Add a webhook integration

1. In the Mondoo App, navigate to the space where you want to set up ticketing and, in the side navigation bar, select Integrations.

2. Select INSTALL INTEGRATION, then choose the Ticket Systems category.

3. Select Webhook.

4. In the Integration Name box, enter a name that clearly shows where the webhook delivers tickets.

5. In the Webhook URL box, enter the HTTPS URL of your endpoint.

6. Under Authentication, choose how your endpoint confirms that a delivery comes from Mondoo. You can turn on either method, or both. To learn how each method works, read Authenticate deliveries.

   • To sign deliveries, enable Sign deliveries, select GENERATE SECRET, then select COPY SECRET and store the secret in your endpoint's configuration. You can also paste a secret you generated yourself.

   • To send a static credential, enable Send an authentication header, then enter the Header name (for example, Authorization) and the Header value (for example, Bearer followed by your token).

   

   Mondoo never shows a signing secret or a header value again after you save the integration. Copy the secret before you select CREATE INTEGRATION.

7. To send a delivery when a ticket is closed in Mondoo, enable Send close notifications.

8. To create a Mondoo ticket and send a delivery when an asset becomes more exposed to attack, enable Automatically create tickets on drift. To learn more, read Automatically create tickets on drift.

9. Select the CREATE INTEGRATION button.

Authenticate deliveries

Anyone who learns your webhook URL can send requests to it. Authentication lets your endpoint reject every request that doesn't come from Mondoo.

Sign deliveries

This is the recommended method. Mondoo signs each delivery with HMAC-SHA256, following the Standard Webhooks specification, and adds three headers:

The secret never leaves Mondoo or your endpoint, so a signature proves both that Mondoo sent the delivery and that nobody changed it on the way. Checking the timestamp also stops an attacker from replaying a delivery they captured.

A signing secret is whsec_ followed by the base64 encoding of 24 to 64 random bytes. The secret Mondoo generates uses 32 bytes.

Send an authentication header

Choose this method when your endpoint, or a gateway in front of it, can check a static credential but can't compute a signature. Mondoo sends the header and its value with every delivery, so the value protects your endpoint only as long as it stays secret. Prefer signing when you can.

Mondoo sets Content-Type, Idempotency-Key, and the webhook-* headers itself, so you can't use those names.

Verify a signed delivery

To verify a delivery, your endpoint must:

1. Read the raw request body. Verify the exact bytes Mondoo sent, before you parse the JSON.

2. Reject the delivery if webhook-timestamp is more than five minutes away from the current time.

3. Decode the part of the secret after whsec_ from base64. Use the result as the HMAC-SHA256 key to sign the string {webhook-id}.{webhook-timestamp}.{body}.

4. Encode the result as base64 and compare it, in constant time, with the value after v1, in each signature in webhook-signature. Accept the delivery if any signature matches.

Any Standard Webhooks library performs these steps for you. If you prefer to verify without a dependency, these examples do the same:

import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60


def verify_mondoo_webhook(secret: str, headers: dict, body: bytes) -> bool:
    """Return True when a delivery is signed with secret and is recent."""
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    signatures = headers["webhook-signature"]

    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for signature in signatures.split(" "):
        version, _, value = signature.partition(",")
        if version == "v1" and hmac.compare_digest(value, expected):
            return True
    return False

Header names are case-insensitive. If your framework doesn't lowercase them, look them up accordingly.

What Mondoo sends

Each delivery is a POST request with a JSON body:

• type is TYPE_CREATED when Mondoo creates a ticket, TYPE_UPDATED when Mondoo updates the ticket, and TYPE_CLOSED when it's closed.

• case holds the Mondoo ticket.

• content holds the ticket's description and comment as Markdown: the finding details, remediation, and affected assets. Mondoo includes it with created and updated tickets.

Mondoo treats a 2xx response as a successful delivery. Any other status code fails the delivery.

Change or rotate authentication

To change authentication, open the integration, select the pencil icon (Edit integration), and go to Authentication. Mondoo shows which methods are on, but never the saved secret or header value.

• To keep a saved secret or header value, leave its box blank.

• To replace one, enter the new value. Mondoo signs with a single secret, so update your endpoint to accept both the old and the new secret, save the new secret in Mondoo, and then remove the old one from your endpoint.

• To stop using a method, turn it off. Mondoo deletes the saved secret or header value.

If you change the webhook URL or the header name, you must enter the header value again. Mondoo never sends a saved header value to an address or header it wasn't entered for. A signing secret is never sent, so it stays in place when the URL changes.

Learn more

• Create Tickets from Advisories

• Create Tickets from Checks

• Manage Ticketing

• Track and Fix Findings with Ticketing