# 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"}}}}}}}}}
```