Create Alert Webhook | Genlogs API Docs

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

Access-TokenstringRequired

JWT Access Token required for authentication

Body

application/json

Schema for creating webhook settings

Field	Type	Description
`webhook_url`	string	uri
`secret`	string	nullable
`description`	string	nullable

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