> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound webhooks

> Subscribe to activity ledger events and receive signed, retried HTTP deliveries.

# Outbound webhooks

Outbound webhooks send matching activity history events to an HTTPS receiver.
Organization members can list
subscriptions and inspect deliveries with an organization-wide API key.
Creating, deleting, and retrying require an organization administrator and a
writable organization API key. Queued events are delivered according to the
subscription state, while listing and deleting stay
available so an organization can always see and remove its subscriptions. Scoped tokens and scoped API keys cannot access
webhook endpoints because a subscription could expose any matching event in the
organization.

Subscriptions match exact activity ledger `verb` values. See [History](https://docs.erdo.ai/history.md)
for the event ledger. The request body is the same `ActivityHistoryEntry` JSON
object returned by `GET /v1/activity/history`:

Provider-object integrations emit `provider_object.created`,
`provider_object.adopted`, and `provider_object.uploaded`. These entries keep
the provider, kind, and account ID in `details` and add the canonical provider
resource ID as `details.external_id` (for Google Ads, the full resource name).

```json theme={null}
{
  "id": "event-id",
  "organization_id": "organization-id",
  "occurred_at": "2026-11-08T12:34:56Z",
  "verb": "resource.published",
  "resource_type": "artifact",
  "resource_id": "page-id",
  "summary": "Published a page",
  "actor_kind": "user",
  "created_at": "2026-11-08T12:34:56Z"
}
```

For example, an upload entry has this payload shape:

```json theme={null}
{
  "verb": "provider_object.uploaded",
  "resource_type": "google_ads.conversion_action",
  "resource_id": "42",
  "details": {
    "provider": "google_ads",
    "kind": "conversion_action",
    "account_id": "1234567890",
    "external_id": "customers/1234567890/conversionActions/42"
  }
}
```

Optional fields such as `details`, actor IDs, `agent_key`, and approval IDs
appear when present on the history entry. Webhook delivery does not introduce a
separate event envelope.

## Workstream status changes

Subscribe to `workstream.status_changed` to learn when long-running work changes
status, including completion, failure, cancellation, and reopening. A write that
leaves the status unchanged emits no status event. Creating a workstream sets its
initial status and does not emit a status-change event.

The event has `resource_type: "workstream"`, the workstream ID in `resource_id`,
its slug in `resource_slug`, and these `details`:

```json theme={null}
{
  "workstream_slug": "quarterly-report",
  "organization_id": "organization-id",
  "old_status": "active",
  "new_status": "completed",
  "source_template_id": "template-id",
  "updated_at": "2026-11-15T12:34:56Z",
  "revision": 12
}
```

`source_template_id` is omitted when the workstream has no source template.
Use `revision` to order changes within one workstream; delivery can arrive out of
order. Deduplicate by event ID and ignore older revisions when maintaining a
current status. A completed agent run alone does not mean the workstream is
completed.

The event carries status facts only. Read `GET /v1/workstreams/{slug}` for the
current workstream and its output resources. A later change may have occurred
before that read, so compare its revision with the event's revision.

```bash theme={null}
erdo webhooks create --url https://hooks.example.net/erdo --verbs workstream.status_changed --include-managed
```

The same verb works in the `verbs` array for `POST /v1/webhooks` and
`erdo_create_webhook`. With `include_managed`, the event's `organization_id`
identifies the managed organization whose workstream changed; read the
workstream in that organization's scope.

## Files attached to a Knowledge record

Subscribe to `knowledge.attachment_added` to learn when a file is attached to a
Knowledge record, instead of polling the record. The event fires once for each
attachment created, whether the file arrived by upload, by a server-side download
from a URL, or by linking a stored file. Re-adding the same file to the same
record (same name and bytes) resolves to the existing attachment and emits
nothing.

The event has `resource_type: "knowledge_object"`, the record's ID in
`resource_id`, and the record's slug and title in `resource_slug` and
`resource_title`. The actor is the person or token that attached the file, or the
system for background work. `details` holds these facts:

```json theme={null}
{
  "attachment_id": "attachment-id",
  "kind": "image",
  "media_type": "image/png",
  "byte_size": 48213,
  "source": "upload",
  "import_batch_id": "batch-id"
}
```

`source` is `upload` for a single file and `import` when Erdo downloaded the file
or added it as part of a multi-file import. `import_batch_id` is shared by every
file of one import: all pages of a folder import, or one multi-file record write.
It is absent for a single-file import. A receiver can wait for the batch to settle
and handle the files together. The event does not include file names, file content, or URLs. Read the record's
attachments for those.

Delivery can arrive out of order, so use `occurred_at` and the event ID to
deduplicate and order events.

```bash theme={null}
erdo webhooks create --url https://hooks.example.net/erdo --verbs knowledge.attachment_added
```

The same verb works in the `verbs` array for `POST /v1/webhooks` and
`erdo_create_webhook`.

## Create and manage subscriptions

Create a subscription with a public HTTPS URL and one or more exact ledger
verbs. Only public destination addresses are accepted. Erdo resolves and checks
the destination at creation and again for every connection, follows no
redirects, and times out a delivery after 10 seconds.

```bash theme={null}
curl -X POST "$ERDO_API_URL/v1/webhooks" \
  -H "Authorization: Bearer $ERDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.net/erdo","verbs":["resource.published","approval.decided"],"include_managed":false}'
```

The response contains the subscription and its plaintext signing secret. The
secret is returned once; store it securely when creating the subscription. A
later `GET /v1/webhooks` returns subscriptions with `secret: "********"`.
Deleting a subscription deactivates it, so it remains in the list with
`active: false`; its delivery history remains available for inspection.

```bash theme={null}
curl "$ERDO_API_URL/v1/webhooks" \
  -H "Authorization: Bearer $ERDO_API_KEY"

curl -X DELETE "$ERDO_API_URL/v1/webhooks/$SUBSCRIPTION_ID" \
  -H "Authorization: Bearer $ERDO_API_KEY"
```

Set `include_managed` to `true` to receive matching events from organizations
currently linked to this organization through a non-revoked, one-hop manager
relationship.

The CLI provides the same operations:

```bash theme={null}
erdo webhooks list
erdo webhooks create --url https://hooks.example.net/erdo --verbs resource.published,approval.decided --include-managed
erdo webhooks deliveries <subscription-id> --status failed
erdo webhooks retry <subscription-id> <delivery-id>
erdo webhooks delete <subscription-id>
```

## Verify a delivery

Each request includes these headers:

| Header | Value |
| - | - |
| `X-Erdo-Event-Id` | Stable ID of the activity ledger event; use it to deduplicate deliveries. |
| `X-Erdo-Timestamp` | Unix timestamp in seconds. |
| `X-Erdo-Signature` | `sha256=<lowercase hex HMAC>` |

The signature is HMAC-SHA256 using the subscription secret over the UTF-8 bytes
of `<unix seconds>.<raw body>`. Verify the signature with a constant-time
comparison, reject timestamps outside your tolerance window, and deduplicate on
`X-Erdo-Event-Id`. Read the raw request bytes before parsing JSON; re-serializing
the body changes the signature input.

Example verification in Node.js:

```js theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody, headers, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
  const timestamp = headers["x-erdo-timestamp"];
  const signature = headers["x-erdo-signature"];
  if (!/^\d+$/.test(timestamp ?? "") || Math.abs(nowSeconds - Number(timestamp)) > 300) return false;
  const expected = `sha256=${createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex")}`;
  const actualBytes = Buffer.from(signature ?? "");
  const expectedBytes = Buffer.from(expected);
  return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
}
```

## Delivery and retries

Delivery is at least once, not exactly once. A receiver can process an event and
fail before Erdo records the success, so the same event ID can be delivered
again. Return a successful 2xx response after accepting the event; use the event
ID to make processing idempotent.

Failed attempts are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, and
6 hours, then hourly until 24 hours have elapsed. After automatic retries end,
the delivery remains visible as failed. Inspect deliveries with
`GET /v1/webhooks/{id}/deliveries?status=failed&limit=50&offset=0` and request a
manual retry with
`POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry`.

The delivery response includes its event and organization IDs, status, attempt
count, next retry time, last HTTP status and error, creation time, and delivery
time when delivered. The optional `status` filter accepts `pending`,
`delivered`, or `failed`; `limit` and `offset` paginate the results.

Manual retry is available only for a failed delivery on an active subscription.
It resets the attempt count and starts a fresh 24-hour retry window immediately;
the delivery's original `created_at` is preserved.

```bash theme={null}
curl "$ERDO_API_URL/v1/webhooks/$SUBSCRIPTION_ID/deliveries?status=failed&limit=50&offset=0" \
  -H "Authorization: Bearer $ERDO_API_KEY"

curl -X POST "$ERDO_API_URL/v1/webhooks/$SUBSCRIPTION_ID/deliveries/$DELIVERY_ID/retry" \
  -H "Authorization: Bearer $ERDO_API_KEY"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.