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). 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

Create webhook settings

Authorizations

APIKeyHeader

Access-TokenstringRequired

JWT Access Token required for authentication

Body

application/json

Schema for creating webhook settings

webhook_urlany ofOptional

string · uri · min: 1 · max: 2083Optional

or

nullOptional

secretany ofOptional

stringOptional

or

nullOptional

descriptionany ofOptional

stringOptional

or

nullOptional

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/alerts/webhook

HTTPcURLJavaScriptPython

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

No content