Agent Hooks

Send signed SeeLLM jobs to your agents, work queues, and automation stack.

Agent Hooks deliver SeeLLM jobs to the tools where work already happens: internal agents, queues, workflow engines, Slack bridges, Linear, GitHub, or a custom endpoint.

The generated OpenAPI contract covers hook creation, listing, and test delivery. The versioned Agent Hook event schema is the machine-readable delivery contract for event names, the current job.created payload, signing, retries, ordering, replay, and secret rotation. These API operations require bearer authentication; hook creation and test delivery require a Firebase admin or editor role (API keys authenticate as editors). The documented endpoints do not enforce endpoint-specific API-key scopes.

Use webhooks as the delivery channel, but treat the product primitive as a SeeLLM job. Your endpoint receives the problem, evidence, recommended action, dashboard link, and action URLs.

See Jobs API for approving actions and attaching patch or edge-page implementations.

Create a Hook

curl -X POST https://api.seellm.link/api/agent-hooks \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent work queue",
    "url": "https://your-company.example/hooks/seellm",
    "events": ["job.created"]
  }'

The response includes a secret once. Store it in your secret manager. SeeLLM does not return it again on list requests.

Hook names are trimmed before validation and the trimmed value must be at most 120 characters; a whitespace-only name is invalid.

Test Delivery

curl -X POST https://api.seellm.link/api/agent-hooks/ah_your_hook_id/test \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

SeeLLM sends a job.created test payload to your endpoint.

The optional domain defaults to example.com; when supplied, it is trimmed and lowercased before the test delivery is built.

Verify Signatures

Every delivery includes:

seellm-event-id: evt_...
seellm-event-type: job.created
seellm-signature: t=1770000000,v1=<hmac_sha256>

Compute the HMAC SHA-256 digest over:

<timestamp>.<raw_request_body>

Use your hook secret as the HMAC key. Verify the signature before parsing JSON: use the exact bytes of the raw request body, not reserialized JSON. Reject signatures whose timestamp is more than five minutes old or lies in the future beyond your allowed clock skew, and reject mismatched signatures.

Payload Shape

{
  "id": "evt_...",
  "event": "job.created",
  "created_at": "2026-05-19T00:00:00.000Z",
  "org_id": "org_...",
  "job": {
    "id": "job_...",
    "type": "ai_attention_gap",
    "domain": "example.com",
    "priority": "high",
    "status": "new",
    "headline": "AI attention is not turning into traffic",
    "summary": "SeeLLM detected AI crawler activity, but AI tool visits are not following.",
    "evidence": [
      { "label": "AI bot visits", "value": 3472, "detail": "Last 7 days" },
      { "label": "AI tool visits", "value": 5, "detail": "Last 7 days" }
    ],
    "recommended_action": "Review the page-level recommendation and approve the fix.",
    "links": {
      "dashboard": "https://app.seellm.link/overview/",
      "api": "https://api.seellm.link/api/agent-hooks"
    },
    "created_at": "2026-05-19T00:00:00.000Z"
  },
  "actions": [
    {
      "id": "approve_fix",
      "label": "Approve recommended fix",
      "method": "POST",
      "url": "https://api.seellm.link/api/jobs/job_.../actions"
    }
  ]
}

Events

The event schema enumerates exactly six subscription names: job.created, job.priority_changed, job.approved, job.dismissed, job.resolved, and job.evidence_updated. job.created is the only event currently delivered; the other five names are accepted when creating a hook but do not currently produce deliveries. Only job.created has a payload schema today.

Errors and Retries

Invalid hook payloads return HTTP 400 with { "error": "..." }; missing hooks return 404, inactive or unsubscribed hooks return 409, and a failed downstream test delivery returns HTTP 502 with { "success": false, "error": "..." }. Current write-role checks throw and surface HTTP 500 rather than an advertised 403, so mutation clients should handle 500 and must not treat 403 as the role-denial contract. The API sends no idempotency key and publishes no hook-specific timeout or automatic-retry policy. For HTTP 429, wait for Retry-After before retrying.

SeeLLM does not automatically retry failed Agent Hook deliveries, does not guarantee delivery order, and has no production-event replay endpoint. Treat seellm-event-id as an idempotency and reconciliation key; the /test endpoint creates a new test event instead of replaying a past production event. There is no in-place signing-secret rotation endpoint: create and verify a replacement hook with a new secret before retiring the previous receiver.