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 ledgerverb values. See History
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).
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 toworkstream.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:
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.
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 toknowledge.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:
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.
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.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.
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:
Verify a delivery
Each request includes these headers:
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:
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 withGET /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.

