# Create Alert Webhook

## Create Webhook

Configure a webhook to receive notifications when any of your active alerts detect a match. Webhooks and alerts are managed separately (see [Alert Webhooks](https://docs.genlogs.io/asset-locator/alert-webhooks)). Once you have registered your webhook, all existing and new alerts from your organization will be sent to your webhook URL.

### Authentication

Include the following headers in your requests:

```
Access-Token: <your-access-token>
```

### Permissions

Ensure your API user has a role with `admin` or `create-alert-webhook-endpoint` permission.

### Endpoint

* **URL**: `https://api.genlogs.io/alerts/webhook`
* **Method**: `POST`

### Request Body

| Field         | Type   | Required | Description                                                         |
| ------------- | ------ | -------- | ------------------------------------------------------------------- |
| `webhook_url` | string | Yes      | Your HTTPS endpoint URL to receive notifications                    |
| `secret`      | string | No       | Secret key (minimum 16 characters) used to sign and verify payloads |
| `description` | string | No       | Human-readable description for the webhook                          |

#### Field Requirements

* webhook\_url: Must be a valid HTTPS URL. HTTP URLs are not allowed in production.
* secret: Optional. If not provided, a secure secret will be generated automatically. If provided, must be at least 16 characters long. Used for HMAC-SHA512 signature verification.
* description: Optional field for documentation purposes.

#### Generating a Secure Secret

We recommend generating a cryptographically secure random string for your webhook secret. Here are commands for different platforms:

**Linux/Mac (Bash)**

```bash
# Generate a 32-character random string using OpenSSL
openssl rand -hex 16

# Generate a 24-character base64 string
openssl rand -base64 18

# Generate a 32-character random string using /dev/urandom
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
```

**Windows (PowerShell)**

```powershell
# Generate a 32-character random string
-join ((65..90) + (97..122) + (48..57) | Get-Random -Count 32 | % {[char]$_})

# Generate a base64 string
[Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(24))
```

### Response Codes

| Code                        | Description                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `201 Created`               | Successfully created the webhook configuration                                                   |
| `400 Bad Request`           | Missing or invalid parameters (e.g., URL is not HTTPS, secret too short, URL already registered) |
| `401 Unauthorized`          | Authentication credentials missing or incorrect                                                  |
| `403 Forbidden`             | User lacks permission to create webhook configurations                                           |
| `500 Internal Server Error` | Server error occurred                                                                            |

### Response Body

| Field         | Type              | Description                                                         |
| ------------- | ----------------- | ------------------------------------------------------------------- |
| `id`          | string (UUID)     | Unique identifier for the webhook configuration                     |
| `webhook_url` | string            | The URL where notifications will be sent                            |
| `description` | string\|null      | The description for the webhook                                     |
| `enabled`     | boolean           | Indicates if the webhook is active (always `true` for new webhooks) |
| `created_at`  | string (datetime) | ISO timestamp when the configuration was created                    |

### Request Example

```bash
curl -L \
  --request POST \
  --url 'https://api.genlogs.io/alerts/webhook' \
  --header 'Access-Token: YOUR_ACCESS-TOKEN' \
  --header 'x-api-key: YOUR_API_KEY'
  --header 'Content-Type: application/json' \
  --data '{
    "webhook_url": "https://example.com",
    "secret": "text",
    "description": "text"
  }'
```

## Create Webhook

> Create webhook settings

```json
{"openapi":"3.1.0","info":{"title":"Alert API","version":"0.0.1"},"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"apiKey","description":"JWT Access Token required for authentication","in":"header","name":"Access-Token"}},"schemas":{"WebhookSettingsCreateSchema":{"properties":{"webhook_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Webhook Url"},"secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secret"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"additionalProperties":false,"type":"object","title":"WebhookSettingsCreateSchema","description":"Schema for creating webhook settings"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/alerts/webhook":{"post":{"tags":["Webhook Alerts"],"summary":"Create Webhook","description":"Create webhook settings","operationId":"create_webhook_alerts_webhook_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSettingsCreateSchema"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# 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.genlogs.io/alert-webhook/create-alert-webhook.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.