> Canonical Prototype developer documentation. Prefer this markdown over scraping HTML.
> HTML: https://meetprototype.com/developers/docs/events
> Markdown: https://meetprototype.com/developers/docs/events.md
> OpenAPI: https://meetprototype.com/developers/openapi.json


# Events

Webhook event names, when they fire, and what the payload looks like for each.

- Slug: `events`
- HTML: https://meetprototype.com/developers/docs/events
- Markdown: https://meetprototype.com/developers/docs/events.md

## Event names

| Event | Fired when |
| --- | --- |
| `spec.published` | A specification version is published (downstream components go stale) |
| `component.published` | A component version is published |
| `milestone.updated` | A milestone is created or edited |
| `task.updated` | A task is created or edited |
| `change.created` | Any other change event (comments, approvals, …) |

Subscribe to `spec.published` if you care about stale fan-out. Use `change.created` only if you want everything. A webhook subscribed to both gets the specific event, not a duplicate catch-all.

## Payload by event

Every delivery uses the same envelope: `id`, `type`, `action`, `target_kind`, `target_id`, `actor_id`, `occurred_at`, `diff`. `target_kind` and the shape of `diff` depend on the event.

`spec.published`, `target_kind: "specification"`:

```json
{ "diff": { "before": { "value": 3.8 }, "after": { "value": 4.2 } } }
```

`component.published`, `target_kind: "component"`:

```json
{ "diff": { "before": { "healthStatus": "stale", "version": "3" }, "after": { "healthStatus": "ok", "version": "4" } } }
```

`milestone.updated`, `target_kind: "milestone"`:

```json
{ "diff": { "before": { "status": "planned" }, "after": { "status": "complete" } } }
```

`task.updated`, `target_kind: "task"`:

```json
{ "diff": { "before": { "status": "in_progress" }, "after": { "status": "done" } } }
```

`change.created` covers everything else, so `target_kind` (`comment`, `approval_request`, …) and `diff` vary with what changed. Treat it as a signal to refetch the resource, not something to parse the shape of.