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

# Webhooks

> Configure Slack, Microsoft Teams, or custom webhook destinations for your alerts.

Webhooks are reusable delivery destinations for [Alerts](/console/notifications/alerts),
configured under **Settings → Webhooks**.

<Note>
  Managing webhooks requires **Admin** permission - a webhook's URL and headers can contain
  secrets, so even viewing one is restricted to Admins.
</Note>

## Add a webhook

<Steps>
  <Step title="Open Webhooks">
    In **Settings → Webhooks**, click **Add webhook**.
  </Step>

  <Step title="Name it">
    Enter a **Name** and an optional **Description**.
  </Step>

  <Step title="Choose a platform">
    Select **Slack**, **Microsoft Teams**, or **Custom**. Leave it unset and the platform is
    detected from the URL.
  </Step>

  <Step title="Enter the URL">
    Paste the **Webhook URL**. Only `https://` URLs are accepted.
  </Step>

  <Step title="Custom only: add authentication">
    Choose **None**, **Token** (Bearer), **API key**, or **Basic**, and enter the corresponding
    credentials.
  </Step>

  <Step title="Custom only: add headers (optional)">
    Add up to 10 static headers to send with every request.
  </Step>

  <Step title="Save">
    Click **Save**. Use **Test webhook** to send a sample payload before relying on it.
  </Step>
</Steps>

## Test a webhook

Click **Test webhook** on a saved webhook. Results show as **Successful**, or a failure reason:
timed out, rejected by the destination (with its status code), or connection failed. A failed test
doesn't block saving.

## Payload

Webhooks receive a JSON POST with `Content-Type: application/json`:

```json theme={null}
{
  "text": "Build \"my-build\" failed on grid \"my-grid\"",
  "alert_name": "...",
  "trigger": "...",
  "grid_name": "...",
  "build_title": "...",
  "build_public_id": "...",
  "build_link": "...",
  "initiator_name": "...",
  "start_time": "...",
  "duration_seconds": "...",
  "status": "...",
  "total_tasks": "...",
  "cache_hit_rate_pct": "..."
}
```

The `text` field is a plain-text message compatible with Slack and Microsoft Teams. Payloads
aren't signed - for a **Custom** webhook, use the authentication and headers you configured to
verify requests on your end.

## URL requirements

* `https://` only.
* Private, loopback, link-local, and other non-routable addresses are rejected, even if they only
  resolve that way at delivery time.
* Cloud provider control-plane APIs (for example AWS IAM/STS/S3, GCP `*.googleapis.com`, Azure
  management/storage endpoints) are blocked. Endpoints you host yourself - Cloud Run, Lambda
  function URLs, Azure App Service, and similar - are allowed.

## Remove a webhook

Deleting a webhook doesn't delete the alerts that use it. If it was an alert's only notification
method, that alert shows a broken destination warning until you assign a new one.