Integration types

Automation: triggers in, webhooks out

Triggers start runs from events and schedules; outbound webhooks report back to your systems — the two directions of the event seam and how they are signed.

Triggers in · Outbound webhooks out · المشغّلات والويب هوك الصادر

The event seam: triggers start runs into Agentic Workforce ME, webhooks notify your systems out of Agentic Workforce ME.

A trigger starts a run from an event or a schedule instead of a person typing — a signed webhook, a cron, a system event. An outbound webhook is how Agentic Workforce ME tells your system what happened — run completed, run failed, approval requested — signed and retried.

المُشغِّل يبدأ التشغيل من حدث أو جدول بدل أن يكتب شخص: ويب هوك موقّع، أو جدولة زمنية، أو حدث من نظام. الويب هوك الصادر هو كيف يُبلغ Agentic Workforce ME نظامك بما حدث — اكتمل التشغيل، فشل التشغيل، طُلبت موافقة — موقّعًا ومع إعادة المحاولة.

Automation is the event seam of the platform, and it has exactly two directions. It is distinct from the copilot’s Automations feature (saved recurring tasks a person sets up in chat) — hence the subtitle the console tab always carries.

In vs out

In — triggers

A signed POST /hooks/:triggerId, a cron, a one-off schedule or a platform event starts a run of a published agent or workflow.

your systems → Agentic Workforce ME

Out — outbound webhooks

run.completed, run.failed, approval.requested delivered to your URL, signed with Hive-Signature and retried.

Agentic Workforce ME → your systems

Triggers

A trigger starts a run from an event or a schedule instead of a person typing — a signed webhook, a cron, a system event.

المُشغِّل يبدأ التشغيل من حدث أو جدول بدل أن يكتب شخص: ويب هوك موقّع، أو جدولة زمنية، أو حدث من نظام.

Kind	Starts a run when	Config
`webhook`	Your backend POSTs to `/hooks/:triggerId` with a valid HMAC signature.	`{ input_mapping?: { <run field>: <top-level body field> } }`; the signing secret is returned once at creation.
`cron`	A cron expression fires in its `timezone`.	`{ cron, timezone?, input? }`
`scheduled`	A single `run_at` instant arrives.	`{ run_at, input? }`
`event`	A platform event the trigger subscribes to occurs.	Per event; see the reference.

Signature. POST /hooks/:triggerId has no API key and no tenant header — authenticity is x-hive-signature: sha256=<hex HMAC-SHA256(secret, raw body)>. A wrong signature is 401 INVALID_SIGNATURE; a valid one answers 202 { run_id }. Compute the HMAC over the exact bytes you send.
Target. A trigger points at a published agent or workflow (target_kind, target_id); an unpublished target is a 409.
Last fired. Every trigger exposes last_fired_at (and next_run_at for schedules); the secret itself is never returned again — only has_secret.
Awaiting first event. A webhook trigger that has been created but never fired shows Awaiting first event in the console rather than a health colour it has not earned; the first valid POST flips it.

The full walkthrough — designing the payload, mapping it onto run input, idempotency, testing with a tunnel — is on Triggers.

Outbound webhooks

An outbound webhook is how Agentic Workforce ME tells your system what happened — run completed, run failed, approval requested — signed and retried.

الويب هوك الصادر هو كيف يُبلغ Agentic Workforce ME نظامك بما حدث — اكتمل التشغيل، فشل التشغيل، طُلبت موافقة — موقّعًا ومع إعادة المحاولة.

Event	Sent when	De-duplicate on
`run.completed`	A run (agent or workflow) reached `succeeded`.	`run.completed:<run_id>`
`run.failed`	A run reached `failed` (model error, tool failure surfaced by the graph, cancellation while waiting).	`run.failed:<run_id>`
`approval.requested`	A run paused on a human-in-the-loop gate; one event per newly pending approval.	`approval.requested:<approval_id>`
`experiment.rolled_back`	An A/B experiment was rolled back (manual or automatic).	`experiment.rolled_back:<experiment_id>`
`payment.executed`	An agent payment (charge or refund) executed under a mandate.	`payment.executed:<payment_id>`
`payment.denied`	A payment attempt was refused by policy or mandate.	`payment.denied:<payment_id>`
`webhook.test`	You called `POST /v1/webhooks/:id/test`.	`webhook.test:<event_id> (never de-duplicated)`

Element	Value
Header	`Hive-Signature`
Format	`t=<unix seconds>,v1=<hex HMAC-SHA256>`
Signed material	`"<t>.<raw body>"` with HMAC-SHA256, keyed with the endpoint secret (shown once at creation, rotatable).
Replay window	300 s either side of your clock (SDK default).
Retries	5 attempts, exponential backoff from 5 s; the same bytes every time, with a fresh signature computed at delivery.
Ledger	`GET /v1/webhooks/:id/deliveries` — status, attempts, last HTTP status and error per event.

Verification code in Node and Python, the retry contract and the delivery ledger are on Webhooks.

API mapping

/v1/triggers and /v1/webhooks take an API key plus X-Tenant-Id and need the admin role for listing, creating, changing, deleting and test deliveries (an API key acts as admin; a console session needs it explicitly). The inbound POST /hooks/:triggerId takes no API key — only the trigger’s signature.

Resource	Path	Notes
Trigger (inbound)	`/v1/triggers`	Kinds `webhook`, `cron`, `scheduled`, `event`; a webhook trigger returns its signing secret once and exposes `last_fired_at`.
Inbound webhook URL	`/hooks/:triggerId`	Public; no API key — authenticity is `x-hive-signature: sha256=<HMAC-SHA256 of the raw body>`; answers `202 { run_id }`.
Outbound webhook endpoint	`/v1/webhooks`	Subscribe a URL to `run.completed`, `run.failed`, `approval.requested`…; `Hive-Signature` over `t.<raw body>`; five attempts with exponential backoff; `GET …/:id/deliveries` is the ledger.