---
title: Receive Signed Agent Hooks
description: Create a job-created hook, verify its HMAC signature, and inspect the delivered job before taking action.
audience: [agent]
type: guide
version: v1
stability: stable
lastVerified: "2026-08-01"
prerequisites: [/docs/api/authentication/, /docs/api/jobs/, /docs/api/agent-hooks/]
related: [/docs/agents/work-with-jobs/, /docs/api/agent-hooks/, /docs/evidence-model/]
artifacts: [{ label: Agent Hook event schema, url: /docs/events/agent-hooks.json }]
---

## 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.

## Recommended path

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](/docs/agents/work-with-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](/docs/events/agent-hooks.json) 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:

```bash
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.

## Related reference

- [Agent Hooks](/docs/api/agent-hooks/)
- [Jobs API](/docs/api/jobs/)
- [Evidence Model](/docs/evidence-model/)