# Webhooks

https://api-docs.lumar.io/docs/graphql/webhooks

Webhooks allow you to receive automated notifications when Protect builds complete. You can configure webhooks to alert on test passes, warnings, or failures.

## Creating a webhook

Use the `createWebhook` mutation to set up an API callback or MS Teams webhook on a project. The mutation's `testSuiteId` parameter accepts your **project ID** (in Lumar's schema, projects and test suites are the same entity).

```graphql
mutation CreateWebhook($input: CreateWebhookInput!) {
  createWebhook(input: $input) {
    webhook {
      id
      url
      alertTypes
      webhookTemplateType
      createdAt
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "testSuiteId": "TjAxMVRlc3RTdWl0ZTEyMw",
    "url": "https://example.com/api/lumar-webhook",
    "alertTypes": ["Pass", "Warning", "Fail"],
    "webhookTemplateType": "MSTeams"
  }
}
```

**Response:**
```json
{
  "data": {
    "createWebhook": {
      "webhook": {
        "id": "TjAzN1dlYmhvb2sx",
        "url": "https://example.com/api/lumar-webhook",
        "alertTypes": ["Pass", "Warning", "Fail"],
        "webhookTemplateType": "MSTeams",
        "createdAt": "2025-01-15T10:00:00.000Z"
      }
    }
  }
}
```

### Webhook template types

| Type      | Description                                                                              |
| --------- | ---------------------------------------------------------------------------------------- |
| `MSTeams` | Sends a formatted message card to a Microsoft Teams channel via an incoming webhook URL. |

For generic HTTP callbacks, use the project-level `apiCallbackUrl` and `apiCallbackHeaders` fields on the project configuration. See [`UpdateProjectInput`](/docs/schema/inputs/update-project-input.md) for details.

## Alert types

Each webhook can be configured to fire on specific alert types:

| Alert Type | Description                           |
| ---------- | ------------------------------------- |
| `Pass`     | All tests in the build passed.        |
| `Warning`  | One or more tests produced a warning. |
| `Fail`     | One or more tests failed.             |

## Slack webhooks

Slack webhooks use a dedicated mutation and integrate directly with Slack incoming webhook URLs.

```graphql
mutation CreateSlackWebhook($input: CreateSlackWebhookInput!) {
  createAutomatorSlackWebhook(input: $input) {
    slackWebhook {
      id
      url
      alertTypes
      createdAt
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "testSuiteId": "TjAxMVRlc3RTdWl0ZTEyMw",
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "alertTypes": ["Pass", "Warning", "Fail"]
  }
}
```

**Response:**
```json
{
  "data": {
    "createAutomatorSlackWebhook": {
      "slackWebhook": {
        "id": "TjAzN1NsYWNrV2ViaG9vazE",
        "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
        "alertTypes": ["Pass", "Warning", "Fail"],
        "createdAt": "2025-01-15T10:00:00.000Z"
      }
    }
  }
}
```

Slack alert types mirror the standard alert types: `Pass`, `Warning`, and `Fail`.

## Querying existing webhooks

Retrieve all webhooks and Slack webhooks configured on a project:

```graphql
query GetWebhooks($testSuiteId: ObjectID!) {
  node(id: $testSuiteId) {
    ... on TestSuite {
      id
      name
      webhooks(first: 10) {
        nodes {
          id
          url
          alertTypes
          webhookTemplateType
          createdAt
        }
        totalCount
      }
      slackWebhooks(first: 10) {
        nodes {
          id
          url
          alertTypes
          createdAt
        }
        totalCount
      }
    }
  }
}
```

**Variables:**
```json
{
  "testSuiteId": "TjAxMVRlc3RTdWl0ZTEyMw"
}
```

**Response:**
```json
{
  "data": {
    "node": {
      "id": "TjAxMVRlc3RTdWl0ZTEyMw",
      "name": "Production SEO Suite",
      "webhooks": {
        "nodes": [
          {
            "id": "TjAzN1dlYmhvb2sx",
            "url": "https://example.com/api/webhook-callback",
            "alertTypes": ["Pass", "Warning", "Fail"],
            "webhookTemplateType": "MSTeams",
            "createdAt": "2025-01-10T08:00:00.000Z"
          }
        ],
        "totalCount": 1
      },
      "slackWebhooks": {
        "nodes": [
          {
            "id": "TjAzN1NsYWNrV2ViaG9vazE",
            "url": "https://hooks.slack.com/services/T00/B00/xxxx",
            "alertTypes": ["Pass", "Warning", "Fail"],
            "createdAt": "2025-01-10T08:00:00.000Z"
          }
        ],
        "totalCount": 1
      }
    }
  }
}
```

## Webhook event reference

| Event                     | Trigger                                            |
| ------------------------- | -------------------------------------------------- |
| Build completed (pass)    | All tests in a build passed their thresholds.      |
| Build completed (warning) | At least one test produced a warning-level breach. |
| Build completed (fail)    | At least one test failed its threshold.            |

For full details on the webhook payload structure, see the [Webhook Notifications documentation](/docs/notifications/webhook-notifications.md).