# Webhooks

This is the easiest way to trigger runs from external tools such as CI pipelines, deployment scripts, workflow builders, or internal services when you do not need the extra control offered by the [CLI](/integrations/api.md) or [API](/running-tests/running-via-api.md).

{% hint style="info" %}
This page covers only incoming webhooks. If you want to configure outgoing webhooks, see [Sending webhook alerts](/collaboration/alerts/sending-webhook.md).
{% endhint %}

### Where to find your webhook URLs

#### Integrations page

Open your project and go to `Integrations` -> `Webhooks`.

This tab shows webhook URL templates with your project webhook token and a placeholder for the test or suite ID.

<figure><img src="/files/ueDSxgIvddNMEhIhjI5B" alt="Integrations page"><figcaption></figcaption></figure>

#### Test and suite actions

To get a webhook URL with specific `test_id` or `suite_id` without building it manually:

1. Open the `...` menu for a test or suite.
2. Click `Run via CLI or webhook`.
3. Open the `Webhook` tab.
4. Copy the generated URL.

<figure><img src="/files/eTfmT6FnpZV5IjG9WlyV" alt="Tests list page"><figcaption></figcaption></figure>

<figure><img src="/files/YUrGzkivU0LFrugpdFhq" alt="Run via modal" width="456"><figcaption></figcaption></figure>

### How to trigger a run

Send a `POST` request to the webhook URL.

No authentication header is required because the webhook token is embedded in the URL.

#### Example: run a test with CURL

```bash
curl -X POST "https://app.bugbug.io/webhooks/<webhook_token>/tests/run/<test_id>"
```

#### Example: run a suite with CURL

```bash
curl -X POST "https://app.bugbug.io/webhooks/<webhook_token>/suites/run/<suite_id>"
```

### Webhook response

If the request is valid, BugBug starts the run and returns `200 OK`.

The response contains the following fields:

| Field        | Type     | Description                                   |
| ------------ | -------- | --------------------------------------------- |
| `id`         | UUID     | ID of the created test or suite run           |
| `modified`   | datetime | Last update time of the run                   |
| `status`     | string   | Current run status, for example `queued`      |
| `webapp_url` | URL      | Direct link to the run details in the web app |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bugbug.io/integrations/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.