Guide
Structure metadata, tags and notification actions
A useful event has two layers: a concise title and body for quick review, plus bounded structured context for finding and acting on it later.
Updated 8 min read
Give each field one clear job
- Use source for the producer, such as backup-worker or research-agent.
- Use tags for reusable categories that you expect to filter across events.
- Use metadata for exact run values such as revision, duration or record counts.
- Use severity for the outcome, not as a substitute for the title.
- Use link actions only for explicit destinations that help investigate or resolve the event.
Do not place passwords, tokens, personal data dumps or complete third-party payloads in metadata. Prefer a safe identifier and a link to the system that already owns the detailed record.
Keep the payload complete but bounded
{
"title": "Backup completed",
"body": "Nightly PostgreSQL backup finished and passed restore verification.",
"severity": "success",
"source": "backup-worker",
"tags": [
"backup",
"production"
],
"deduplicationKey": "backup:2026-07-31",
"metadata": {
"duration": "42s",
"size": "1.8 GB"
},
"actions": [
{
"id": "open-backup",
"type": "link",
"label": "Open backup",
"href": "https://example.com/backups/2026-07-31",
"style": "primary"
}
]
}Frequently asked questions
- Does the producer need a special integration?
- No. The examples use an authenticated HTTPS request, so any script, service or visual workflow that can send HTTP can use the same contract.
- Should credentials be included in notification data?
- No. Keep credentials in the producer's secret store and send only the context needed to understand or locate the event.
Keep exploring
Put the pattern to work
Existing accounts can open the inbox and send their next event.