API Reference
One endpoint, one POST request. Send JSON to your channel's webhook URL and we handle notifications, formatting, and delivery.
Send Alert
Trigger a new alert in a specific channel. This is the primary endpoint for sending notifications from your application.
POST https://zenhook.dev/api/webhook/{token}
Example Request
curl -X POST https://zenhook.dev/api/webhook/abc123def456 \
-H "Content-Type: application/json" \
-d '{
"title": "New User Signup",
"level": "success",
"emoji": "🎉",
"source": "My App",
"message": "[email protected] just joined your workspace.",
"linkUrl": "https://myapp.com/admin/users/42",
"linkText": "View Profile"
}'Path Parameters
token string Required
Your unique channel webhook token. Find it in channel settings.
Request Body
title string Required
A brief summary of the alert. Used as the headline in notifications. Max 200 characters.
level enum
Severity of the alert:
info, success, warning, error. Defaults to info.
message string
Detailed body text. Max 5,000 characters.
emoji string
Custom emoji displayed next to the title. Accepts a unicode
character (
"🚀"), a
name ("rocket"),
or a shortcode (":rocket:").
Names and shortcodes are translated on ingest. Unknown names are
dropped rather than rendered as literal text. Known names: rocket · siren · warning · check · cross · fire · bug · zap · bell · tada · sparkles · envelope · chat · phone · megaphone · wave · eyes · heart · thumbsup · office · door · house · factory · lock · unlock · key · link · package · gear · wrench · shield · money · chart · clock · hourglass · flag · star · target · pin · tag · computer · server · database · cloud · bulb · gem · anchor · pick · bank.
fields array
Key-value objects for structured data. Each object has
label and value.
linkUrl string
URL for a clickable call-to-action link displayed below the title.
linkText string
Label for the link button. Defaults to "View" if
linkUrl is set.
attachments array
Up to 8 media items shown inside the alert. Each object takes a
url plus an optional
type
(image,
video, or
audio) and
name caption. Zenhook fetches each
URL and re-hosts the file on its own CDN — your media loads fast
and your source URLs stay private. Supported: PNG, JPEG, GIF, WebP,
AVIF, MP4, WebM, MP3, WAV, M4A, Ogg (SVG is rejected). Max 10 MB
per image, 25 MB audio, 50 MB video.
source string
Author name shown in the alert header (e.g. "GitHub", "Stripe"). Defaults to "Webhook".
metadata object
Arbitrary JSON object shown as an expandable "Raw Payload" section with copy-to-clipboard. Max 10 KB.
Responses
201 Created
Alert received and queued for delivery.
json
{
"success": true,
"alertId": "clx1234567890abcdef",
"queuedAt": "2024-03-22T12:00:00Z"
}Structured Data
Use the fields array to include rich metadata
displayed in the dashboard and email alerts.
Example with fields
{
"title": "Build Failed",
"level": "error",
"fields": [
{ "label": "Branch", "value": "main" },
{ "label": "Commit", "value": "abc123f" },
{ "label": "Author", "value": "John Smith" },
{ "label": "Error", "value": "npm install timed out after 300s" }
],
"attachments": [
{ "url": "https://ci.example.com/runs/123/screenshot.png", "type": "image" }
],
"linkUrl": "https://github.com/org/repo/actions/runs/123",
"linkText": "View Logs"
}Reading alerts back out
The webhook endpoint above is public and write-only — anyone with the channel token can post into it. To list alerts, mark them read, or build an integration that consumes them, use the authenticated Read API with a Bearer token.