# Structure metadata, tags and notification actions

Keep project notifications readable and structured for people and agents, with filterable context outside chat prose.

A useful project notification has two layers: a concise title and body, plus bounded structured context that people and agents can interpret without reconstructing chat prose.

Published: 2026-07-31. Updated: 2026-08-24.

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

**Structured backup event**

```json
{
  "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"
    }
  ]
}
```

> **Links are safer than arbitrary commands.** A link action makes the destination visible and leaves execution in the target system. It does not claim that receiving the event can run arbitrary code.

## 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.

### Why send this to FYInbox instead of chat or email?

FYInbox gives project notifications one structured, reviewable home instead of scattering them through Slack, Telegram and email. Those tools remain useful for conversations and intentional messages.

### Why structure notifications for people and agents?

People and agents both need stable source, outcome and next-action context. FYInbox keeps that context in one notification record outside conversation streams.

[Guides index](/guides)