## 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)**

```
# 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)**

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

```
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

post/alerts/webhook

Create webhook settings

Authorizations

APIKeyHeader

APIKeyHeader

Access-TokenstringRequired

JWT Access Token required for authentication

Body

application/json

application/json

Schema for creating webhook settings

| Field        | Type            | Description                            |
|--------------|-----------------|----------------------------------------|
| `webhook_url` | string | uri | min: 1 | max: 2083 | nullable | Optional |
| `secret`      | string | nullable              | Optional |
| `description` | string | nullable | Optional |

Responses

| Code | Description                |
|------|----------------------------|
| 201  | Successful Response         |
| 422  | Validation Error            |

HTTP

```
POST /alerts/webhook HTTP/1.1
Access-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "webhook_url": "https://example.com",
  "secret": "text",
  "description": "text"
}
```

201

Successful Response

```
No content
```