{
  "version": "1.0.0",
  "generated_at": "2026-08-01T00:00:00.000Z",
  "canonical_docs_url": "https://seellm.com/docs/api/agent-hooks/",
  "stability": "stable",
  "events": [
    "job.created",
    "job.priority_changed",
    "job.approved",
    "job.dismissed",
    "job.resolved",
    "job.evidence_updated"
  ],
  "schemas": {
    "event": {
      "type": "string",
      "enum": [
        "job.created",
        "job.priority_changed",
        "job.approved",
        "job.dismissed",
        "job.resolved",
        "job.evidence_updated"
      ],
      "$schema": "http://json-schema.org/draft-07/schema#"
    },
    "payloads": {
      "job.created": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "event": {
            "type": "string",
            "const": "job.created"
          },
          "created_at": {
            "type": "string"
          },
          "org_id": {
            "type": "string"
          },
          "job": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "ai_attention_gap",
                  "new_ai_crawler",
                  "page_error",
                  "citation_opportunity"
                ]
              },
              "domain": {
                "type": "string"
              },
              "page_url": {
                "type": "string"
              },
              "priority": {
                "type": "string",
                "enum": [
                  "high",
                  "medium",
                  "low"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "new",
                  "reviewed",
                  "approved",
                  "sent",
                  "dismissed",
                  "resolved"
                ]
              },
              "headline": {
                "type": "string"
              },
              "summary": {
                "type": "string"
              },
              "evidence": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "value": {
                      "type": [
                        "string",
                        "number"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "label",
                    "value"
                  ],
                  "additionalProperties": false
                }
              },
              "recommended_action": {
                "type": "string"
              },
              "links": {
                "type": "object",
                "properties": {
                  "dashboard": {
                    "type": "string"
                  },
                  "api": {
                    "type": "string"
                  }
                },
                "required": [
                  "dashboard",
                  "api"
                ],
                "additionalProperties": false
              },
              "created_at": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "type",
              "domain",
              "priority",
              "status",
              "headline",
              "summary",
              "evidence",
              "recommended_action",
              "links",
              "created_at"
            ],
            "additionalProperties": false
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "method": {
                  "type": "string",
                  "const": "POST"
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "label",
                "method",
                "url"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "id",
          "event",
          "created_at",
          "org_id",
          "job",
          "actions"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      }
    },
    "delivery": {
      "signature_headers": {
        "type": "object",
        "properties": {
          "seellm-event-id": {
            "type": "string",
            "minLength": 1
          },
          "seellm-event-type": {
            "type": "string",
            "enum": [
              "job.created",
              "job.priority_changed",
              "job.approved",
              "job.dismissed",
              "job.resolved",
              "job.evidence_updated"
            ]
          },
          "seellm-signature": {
            "type": "string",
            "pattern": "^t=\\d+,v1=[a-f0-9]{64}$"
          }
        },
        "required": [
          "seellm-event-id",
          "seellm-event-type",
          "seellm-signature"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "attempt_metadata": {
        "type": "object",
        "properties": {},
        "additionalProperties": false,
        "description": "Agent Hook deliveries do not include per-attempt metadata.",
        "$schema": "http://json-schema.org/draft-07/schema#"
      }
    }
  },
  "delivery": {
    "version": "1.0.0",
    "canonical_docs_url": "https://seellm.com/docs/api/agent-hooks/",
    "stability": "stable",
    "signature": {
      "algorithm": "HMAC-SHA256",
      "input": "<timestamp>.<raw_request_body>",
      "headers": [
        "seellm-event-id",
        "seellm-event-type",
        "seellm-signature"
      ],
      "header_format": "t=<timestamp>,v1=<hmac_sha256>"
    },
    "timestamp": {
      "max_age_seconds": 300,
      "guidance": "Receivers should reject signatures older than five minutes."
    },
    "retries": {
      "automatic": false,
      "guidance": "SeeLLM does not automatically retry failed deliveries."
    },
    "ordering": {
      "guaranteed": false,
      "guidance": "Delivery order is not guaranteed; use seellm-event-id for idempotency and reconciliation."
    },
    "replay": {
      "available": false,
      "guidance": "There is no production-event replay endpoint; test delivery creates a new job.created event."
    },
    "secret_rotation": {
      "supported": false,
      "guidance": "Create and verify a replacement hook with a new secret; there is no in-place secret rotation endpoint."
    }
  }
}