Use case · Agent webhooks

Real-time webhooks for AI agent file events.

Get notified the moment your AI agent writes a file or finishes a command. Signed payloads, namespace-scoped subscriptions, no polling. Trigger Slack messages, kick off pipelines, fan out to downstream agents — in the same handler.

Get an API keyRead the docs
1.0 THE PROBLEM

You shouldn't have
to poll your agent.

Long-running agents do work over minutes — sometimes hours. Knowing when one is finished, when a checkpoint lands, or when a report is ready usually means polling a status endpoint, racing on filesystems, or running scheduled jobs that drift out of sync with reality.

TroveFiles fires a signed webhook the instant the filesystem changes. Your backend reacts in the same handler — Slack, pipeline trigger, downstream agent — without a background worker watching the workspace.

2.0 EVENTS

What TroveFiles fires.

file.written

Any time the agent creates or modifies a file. Includes path, size, and namespace.

exec.completed

Any shell command the agent runs, after it finishes. Includes command, exit code, and stdout snippet.

file.deleted

When the agent removes a file. Useful for audit logs and lifecycle pipelines.

key.created

A new scoped key was issued from your admin key. Mirror to your audit log.

key.revoked

A key was revoked. Trigger downstream cleanup or customer-offboarding flows.

webhook.test

Synthetic event you can fire from the dashboard to verify your handler.

3.0 THE PATTERN

Subscribe. Verify. React.

01

Subscribe per namespace

At customer provisioning time, register a webhook for that namespace. Each tenant's events stay scoped to its own subscription.

from trove_sdk import TroveAdminClient

admin = TroveAdminClient(api_key="trove-admin-...", workspace_id="ws-abc123")

# Subscribe per customer namespace at provision time
admin.create_webhook(
    url="https://api.yourapp.com/trove-events",
    events=["file.written", "exec.completed"],
    namespace="customer-acme",
)
02

Verify and react

Pass the body, secret, and signature header to verify_webhook(). Reject invalid signatures. React in the same handler — Slack, database update, downstream agent.

from trove_sdk import verify_webhook, WebhookSignatureError
from fastapi import FastAPI, Request, HTTPException
import httpx, os

app = FastAPI()

@app.post("/trove-events")
async def receive(request: Request):
    body = await request.body()
    try:
        event = verify_webhook(
            secret=os.environ["TROVE_WEBHOOK_SECRET"],
            body=body,
            signature_header=request.headers["x-trove-signature"],
        )
    except WebhookSignatureError:
        raise HTTPException(status_code=400)

    # React in the same handler — no polling
    if event.type == "file.written" and "reports/" in event.data["path"]:
        await httpx.AsyncClient().post(SLACK_WEBHOOK, json={
            "text": f"Report ready for {event.namespace}: {event.data['path']}"
        })
    return {"ok": True}
4.0 COMMON PATTERNS

What teams build with this.

file.writtenAgent finishes a quarterly report→Notify the user on Slack with a deep-link to the file
file.writtenAgent saves an intermediate checkpoint→Kick off the next stage of a multi-step pipeline
exec.completedAgent runs any shell command→Stream the command + exit code to your audit log
file.writtenAgent A produces output for Agent B→Trigger Agent B with the new file as input
key.revokedA scoped key is revoked→Run customer-offboarding cleanup in your billing system
5.0 FAQ

Agent webhooks,
answered.

What events do TroveFiles webhooks fire on?

file.written (any path your agent writes), exec.completed (any shell command finishes), and key lifecycle events (created, revoked). You subscribe to the events you care about per namespace; everything else is filtered out.

How are TroveFiles webhooks signed?

Each request includes an x-trove-signature header. Pass the raw body, secret, and signature header to verify_webhook() in the SDK; if the signature is invalid, it raises WebhookSignatureError so you can reject the request.

Can I scope webhooks to one customer?

Yes. Pass namespace="customer-X" when creating a webhook. TroveFiles only fires events from that namespace to that endpoint, so each tenant's events stay separate even if they share infrastructure.

What happens if my endpoint is down?

TroveFiles retries with exponential backoff for a configurable window. Failed deliveries are visible in the dashboard for replay; you can also call the test endpoint to verify your handler accepts a synthetic event.

How do I avoid duplicate side effects?

Every event has a unique id. Make your handler idempotent — record the event id when you process it and short-circuit if you see it again. TroveFiles may retry, so duplicate-resistant handlers are required.

Can I trigger another agent from a webhook?

Yes — that's a common pattern. When agent A writes a checkpoint, your handler kicks off agent B with that file as input. Multi-stage agent pipelines work cleanly because every stage transition is an explicit signed event.

Wire your agent
into the rest of your stack.

Subscribe in one call. Verify with one SDK function. React in the same handler — no background workers, no polling.

Get started freeSee multi-tenant agents