Docs/ agents/ Receive Signed Agent Hooks
guidev1stableVerified 2026-08-01

Receive Signed Agent Hooks

Create a job-created hook, verify its HMAC signature, and inspect the delivered job before taking action.

Prerequisites

  • A publicly reachable HTTPS endpoint able to retain the raw request body for signature verification.
  • An API key and a secure store for the hook secret returned at creation time.
  • A receiver that rejects signatures older than five minutes and mismatched signatures.
  1. Create a hook subscribed to job.created and save the returned secret immediately.
  2. On delivery, read seellm-event-id, seellm-event-type, and seellm-signature.
  3. Compute HMAC SHA-256 over the exact string <timestamp>.<raw_request_body> with the stored hook secret. The signature header is formatted as t=<timestamp>,v1=<hmac_sha256>.
  4. Reject stale (more than five minutes old), future-skewed, or mismatched requests before parsing the job as trusted work.
  5. Use the delivered job’s dashboard link and action URLs to continue through Work With SeeLLM Jobs.

Expected result

Your endpoint receives a signed job.created payload containing the job, its evidence, recommended action, dashboard link, and action URLs. The secret is returned only once and is not available from later list requests. See the versioned Agent Hook event schema for all six accepted event names and the exact current payload schema.

Verify

Create a test delivery, then confirm your receiver logs a valid job.created signature verification without logging the secret:

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"}'

Troubleshooting

  • If the signature fails, hash the exact raw body, not reserialized JSON, using <timestamp>.<raw_request_body>.
  • If a delivery is stale, reject it and investigate the sender or receiver clock.
  • SeeLLM does not automatically retry failures, guarantee delivery order, or expose a production-event replay endpoint. Deduplicate and reconcile using seellm-event-id; /test sends a new test event rather than replaying an old one.
  • If you no longer have the secret, create and verify a replacement hook rather than expecting it to be returned by a list request. There is no in-place secret rotation endpoint; overlap receiver support for the old and new secret until the previous receiver is retired.