---
title: webhook operations
---

The exact fields each `webhook.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/reference/http-api#request) its namespace and agent; see [identities and namespaces](/concepts/identities-and-namespaces). The [operations index](/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `webhook.deliveries`

The namespace's webhook events of the last 3 days and their delivery state.

`POST /v1/webhook.deliveries` · MCP `loom_webhook_deliveries` · role `admin` · idempotent · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `webhook_id` | `str` | `''` | Only this webhook's events; "" = every webhook of the namespace. |
| `status` | `Literal['pending', 'delivered', 'dead'] \| None` | `None` | Only events in this state; None = every state. |
| `limit` | `int` | `100` | At most this many events, newest first, 1-500. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `deliveries` | `list[WebhookDelivery]` | Events, newest first. |

## `webhook.list`

The namespace's memory webhooks.

`POST /v1/webhook.list` · MCP `loom_webhook_list` · role `admin` · idempotent · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `webhooks` | `list[WebhookInfo]` | The namespace's live registrations, oldest first. |

## `webhook.register`

Register a URL that is told when memory in the namespace changes.

`POST /v1/webhook.register` · MCP `loom_webhook_register` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `url` | `str` | required | Where events are POSTed: an https URL (http only where the deployment allows it) whose host resolves to public addresses. |
| `secret_ref` | `str` | required | Name of the environment variable holding the signing secret (never the secret): `LOOM_WEBHOOK_SECRET_<ORG>__<NAME>`, ORG the org id upper-cased with every byte other than a-z and 0-9 as `_` plus two hex digits. |
| `events` | `list[Literal['memory.written', 'memory.revised', 'memory.tombstoned', 'memory.restored', 'memory.redacted', 'memory.erased']]` | *(computed)* | The event types to send; default every one. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `webhook` | `WebhookInfo` | The registration as stored. |

## `webhook.remove`

Remove one memory webhook; none of its events is sent after the call, save a POST already in flight.

`POST /v1/webhook.remove` · MCP `loom_webhook_remove` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `webhook_id` | `str` | required | The webhook_id webhook.register or webhook.list returned. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `removed` | `bool` | False when the namespace has no live webhook with that id. |

<!-- prettier-ignore-end -->
