Validate Webhook

POST/api/v2/webhooks/validate

Validates a webhook body against the same schema, URL rules, and body template check used by POST /api/v2/webhooks. The webhook is never persisted. Use this endpoint at plan time (e.g. from a Terraform provider) to check that a webhook configuration is valid before applying it. Name uniqueness is not checked.

Authorizations

AuthorizationBearer API Keyheaderrequired
`Authorization: Bearer <token>`

Request bodyJSON

namestringrequired
Webhook name. Must be unique per service within the team.

maxLength: 1024
Example: "Production Alerts"
serviceslackorincidentioorgenericrequired
Webhook service type.

Example: "slack"
urlstringrequired
Webhook destination URL.

format: uri, maxLength: 2048
Example: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
descriptionoptionalstring
Webhook description, shown in the UI.

maxLength: 2048
Example: "Sends critical alerts to the #incidents channel"
bodyoptionalstring
Optional Handlebars request body template. Only for generic/incidentio; rejected for slack. Rejected with a 400 if it does not compile or calls a helper other than eq and the Handlebars built-ins.

maxLength: 16384
Example: "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}"
headersoptionalmap ofstring
Write-only. Custom HTTP headers sent with the webhook request. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

Example: {"Authorization":"Bearer secret-token"}
queryParamsoptionalmap ofstring
Write-only. Query parameters appended to the webhook URL. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

Response

JSON

200

Validation result. HTTP 200 is always returned for valid and invalid bodies — a non-200 response means the request itself failed (auth, server error, etc.).

JSON

validbooleanrequired
True when the body passes all validation rules.
errorsarray ofobjectrequired
Validation errors. Empty when valid is true.
2 properties
- pathstringrequired
  Dot-separated field path, or empty string for top-level errors.
- messagestringrequired
  Human-readable error description.
normalizedobjector nullrequired
The parsed webhook body, without the write-only headers and queryParams. Populated when valid is true, null when valid is false.

Validate Webhook

curl --request POST \
  --url '<base-url>/api/v2/webhooks/validate' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production Alerts",
  "service": "slack",
  "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
  "description": "Sends critical alerts to the #incidents channel",
  "body": "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}",
  "headers": {
    "Authorization": "Bearer secret-token"
  },
  "queryParams": {
    "property1": "string",
    "property2": "string"
  }
}
'

const url = '<base-url>/api/v2/webhooks/validate';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    name: 'Production Alerts',
    service: 'slack',
    url: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX',
    description: 'Sends critical alerts to the #incidents channel',
    body: '{"alert": "{{title}}", "severity": "{{level}}"}',
    headers: {Authorization: 'Bearer secret-token'},
    queryParams: {property1: 'string', property2: 'string'}
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "<base-url>/api/v2/webhooks/validate"

payload = {
    "name": "Production Alerts",
    "service": "slack",
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "description": "Sends critical alerts to the #incidents channel",
    "body": "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}",
    "headers": { "Authorization": "Bearer secret-token" },
    "queryParams": {
        "property1": "string",
        "property2": "string"
    }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "valid": true,
  "errors": [],
  "normalized": {
    "name": "Alerts",
    "service": "generic",
    "url": "https://example.com/webhooks/alerts",
    "body": "{\"alert\": \"{{title}}\"}"
  }
}

{
  "message": "Unauthorized access. API key is missing or invalid."
}

{
  "message": "NOT_FOUND: Alert not found"
}

Report an issue