smart_toy Integration guide for AI agents

Alarum is a centralized webhook/event hub. Scripts, CI pipelines, cron jobs and services send events over a single HTTP POST. The user reads them in a unified inbox, gets push notifications, and can re-forward them to Discord or Slack. This page explains how to integrate event-sending into a user's project.

description A plain machine-readable version of this guide lives at /llms.txt . Fetch that directly.

key Getting a token

Tokens are created by the human user in the Alarum UI (a project's Settings → Tokens, or its Integration tab). A token looks like alrm_… and belongs to exactly one project. You do not create tokens yourself, ask the user to create a project + token and hand you the token. Treat it as a secret: env var or CI secret, never committed.

api Ingestion endpoint

POST https://alarum.me/h
Authorization: Bearer <TOKEN>
Content-Type: application/json

(body = the event payload, JSON)

204, event accepted
400, invalid payload (bad JSON, missing title, invalid level)
401, unknown or revoked token
429, rate limit hit (1000 events/hour/token), with a Retry-After header

data_object Payload schema

Native alarum format. Only title is required.

Field	Type	Required	Notes
level	enum	optional	info \| success \| warn \| error \| critical, default "info"
title	string	required	max 256 chars
message	string	optional	max 8000 chars, multi-line OK
tags	string[]	optional	max 16, each max 32 chars, slugified
source	string	optional	max 64, e.g. "github-actions"
url	string	optional	max 1024, link shown in the event detail
fields	object[]	optional	max 25, { name, value, inline }, Discord-embed style
timestamp	string	optional	ISO 8601, event time; defaults to received time
footer	string	optional	max 256
author	object	optional	{ name, url }
color	string	optional	#RRGGBB hex, overrides the level color

stack Levels & semantics

infoNeutral informational event. Push OFF by default.

successSomething completed OK. Push ON by default.

warnNeeds attention but not broken. Push ON.

errorSomething failed. Push ON.

criticalUrgent failure. Push ON; can bypass quiet hours.

Pick the level that matches real severity, don't send everything as error.

sync_alt Accepted formats

The format is auto-detected. alarum = the native schema above (use this). discord = a Discord webhook payload ({ "embeds": [...] }) is accepted and normalized. raw = any other JSON is stored as-is in the message field. Force it with the header X-Alarum-Format: alarum|discord|raw.

code Examples in every language

Pick a language or runner. The snippet auto-fills with a sample payload; replace <YOUR_TOKEN> with a real token the user gives you.

POST https://alarum.me/h

curl -X POST 'https://alarum.me/h' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"level":"success","title":"Deploy succeeded","message":"v1.2.3 shipped to production","source":"github-actions"}'

11 ready-made examples: cURL, GitHub Actions, GitLab CI, Codeberg CI, JavaScript (fetch + axios), Python, PHP, Go, Ruby, PowerShell, generic Bash. Same payload schema across all of them. Pick yours in the dropdown above.

checklist Best practices

Send events at meaningful checkpoints: deploy done, build failed, backup completed, cron ran, error caught.
One token per source, the user can revoke a token without affecting others.
Give a clear, human-readable title, it's what shows in the inbox list and the push notification.
Use source to identify where the event came from; use tags for filtering.
Don't spam, the limit is 1000 events/hour/token. Batch or throttle noisy sources.
The token is a secret. Env var / CI secret only, never commit it.

info No management API (yet)

There is currently no API to create / edit / delete projects or tokens, everything is managed by the human in the Alarum UI. If you need a project or a token, ask the user to create it and give it to you.