Skip to main content

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 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).
For example, an upload entry has this payload shape:
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:
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.
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:
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.
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.
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.
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:

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