One boundary, two directions

Webhooks

Let an outside system trigger work here, or be told when something finished.

The three kinds of webhookTwo inbound webhooks and one outbound. A wake-up webhook checks its token, your ownership of the chat and container, rate limits and credit before it starts a frozen goal job. An event webhook applies the same token and ownership checks and appends the request to a file in the container. A decision webhook sends a signed request to your URL and uses your reply, or the built-in evaluator if you do not answer in time.Wake-up webhook (inbound)CI or Zapier sendsPOST /api/hook/tokenToken known? Chat andcontainer still yours?Rate limits andprepaid creditWake container,start frozen /goal jobEvent webhook (inbound)Service sendsPOST /api/inject/tokenSame token andpair checks, rate limitAppend one JSON line toincoming.jsonl inthe containerDecision webhook (outbound)answeredfailed or blockedEvent in your chat:approval, risk, tool callSigned POST toyour URLYour reply: continue,stop, approve, deny or askNo answer in time:built-in evaluator decides
Inbound webhooks check the token and who owns the target before anything runs; the outbound one falls back to ZeroLog's own evaluator.
Diagram as text
  1. Wake-up webhook: an outside system sends POST /api/hook/<token>.
  2. ZeroLog looks the token up by its hash and checks that the chat and container still belong to you and are attached to each other. An unknown or revoked token gets a 404 that reveals nothing.
  3. It applies the per-minute and per-day limits and checks that you have prepaid credit left.
  4. It wakes the container unless you switched that off, and starts a /goal job with the model, objective, criteria and spend cap frozen in the webhook.
  5. Event webhook: an outside system sends POST /api/inject/<token>. The same token and ownership checks and a per-minute limit apply.
  6. ZeroLog appends one JSON line (method, headers without secrets, body) to /work/.webhooks/incoming.jsonl in the container.
  7. Decision webhook: when an event you subscribed to happens in your chat, ZeroLog sends a signed POST to your URL.
  8. If your service answers with continue, stop, approve, deny or ask, ZeroLog uses it. On timeout, error or a blocked target, the built-in evaluator decides instead.

Outside

ZeroLog

From · Outside

An outside system sends a request.

Inbound

Accepted

To · ZeroLog

The request triggers work here.

From · ZeroLog

Something here finished.

Outbound

To · Outside

The outside system is told.

Only authorised requests are accepted

Unauthorised incoming requests are rejected before they can trigger work. The token in the URL is the credential. An unknown or revoked token gets a 404, so a guess reveals nothing.

The square on the inbound path above

The three kinds

Wake-up webhook · inbound

An outside system such as CI, GitHub Actions or Zapier sends POST /api/hook/<token>. ZeroLog starts a /goal job in the chat and container you attached to the webhook, and answers 202 with the job number.

  • Model, objective, completion criteria and spend cap are frozen in the webhook. By default the caller cannot change them. If you allow it, the caller can append free text of up to 4,000 characters.
  • A paused container is woken first, unless you turned that off.
  • Limits per webhook: 6 triggers a minute and 100 a day by default, up to 60 and 1,000. Beyond that the answer is 429. With no prepaid credit left the answer is 402. Each account can have 3 active wake-up webhooks.
  • The token is shown once when you create the webhook and is stored only as a hash. A browser visit (GET) is refused with 405.

Event webhook · inbound

Real events from Stripe, GitHub or another service are posted to POST /api/inject/<token>. ZeroLog appends each one as a line of JSON to /work/.webhooks/incoming.jsonl in the container, so the agent can build and test against actual payloads.

  • Each line holds the time, method, headers and body. Authorization, cookie and API-key headers are replaced before anything is written.
  • Bodies up to 256 kB are accepted. The default limit is 60 events a minute, up to 120.
  • This kind has no settings screen yet. You create and revoke it through the API (/api/injects).

Decision webhook · outbound

You give ZeroLog a URL, an optional secret and the events you care about: goal_set, turn_end, needs_approval, risk_check, goal_done and tool_call. When one happens, ZeroLog sends a signed POST and acts on your reply: continue, stop, approve, deny or ask, with an optional instruction and reason.

  • With a secret, each request carries an X-ZeroLog-Signature header with a timestamp and an HMAC-SHA256 of the body. Receivers should reject timestamps older than five minutes.
  • The timeout is 5 seconds by default, between 1 and 30. ZeroLog retries once.
  • If your service fails, times out or is not an allowed destination, ZeroLog's built-in evaluator decides instead. Redirects are not followed.

Manage the wake-up and decision kinds under Settings, Webhooks.