Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

The /event-subscriptions endpoints let you register a URL to receive AgentRail task lifecycle events as outbound HTTP POST requests. Webhook delivery is at-least-once with exponential backoff for up to 8 attempts. Your endpoint must deduplicate on X-AgentRail-Event-Id — this header remains stable across retries, while X-AgentRail-Delivery-Id changes on each attempt. AgentRail signs every outbound delivery using HMAC-SHA256 over the raw request body with the subscription secret you provide at creation time. Always verify the X-AgentRail-Signature header before processing a delivery.
Required scopes: webhooks:read (list), webhooks:write (create/delete)

​
Create a subscription

​
POST /event-subscriptions

​
Headers

​
Idempotency-Key
string
required
Unique key for safe retries. The same key plus the same body replays the original accepted result. Reusing the key with a different body returns 409 conflict. Must be 8–128 characters.

​
Request body

​
url
string
required
Your HTTPS endpoint URL that will receive event deliveries.
​
eventTypes
string[]
required
Non-empty list of event types to subscribe to.Allowed values: task.updated, task.reviewed, task.shipped, task.awaiting_user
​
secret
string
required
Shared secret used to compute and verify the X-AgentRail-Signature on each delivery. Must be 16–128 characters. Store this value securely — AgentRail never returns it after creation.
​
description
string
Optional description for this subscription. Maximum 200 characters.
​
filters
object
Optional filter set to narrow event delivery.

​
Example

curl -s -X POST "$AGENTRAIL_BASE_URL/event-subscriptions" \
  -H "authorization: Bearer $AGENTRAIL_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: whsub-primary-v1" \
  -d '{
    "url": "https://agents.example.com/webhooks/task-events",
    "eventTypes": ["task.updated", "task.reviewed", "task.shipped"],
    "secret": "whsec_live_agentrail_contract_001",
    "description": "Primary automation endpoint for task lifecycle updates.",
    "filters": {
      "taskIds": ["tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V"]
    }
  }'

​
Response

A 201 response confirms the subscription was created.
​
data
object
required
The created subscription record.

​
List subscriptions

​
GET /event-subscriptions

curl -s "$AGENTRAIL_BASE_URL/event-subscriptions" \
  -H "authorization: Bearer $AGENTRAIL_API_KEY"
Returns an array of subscription records in the same shape as the create response. Requires webhooks:read.

​
Inbound delivery headers

AgentRail sends the following headers with every outbound webhook delivery:
HeaderDescription
x-agentrail-subscription-idThe subscription that triggered this delivery. Pattern: evsub_[A-Za-z0-9]+.
x-agentrail-event-idStable logical event ID. Deduplicate on this value. Pattern: evt_[A-Za-z0-9]+.
x-agentrail-event-typeEvent type, for example task.reviewed.
x-agentrail-delivery-idUnique delivery attempt ID. Changes on each retry. Pattern: dlv_[A-Za-z0-9]+.
x-agentrail-delivery-attemptMonotonic retry attempt number, starting from 1.
x-agentrail-signatureHMAC-SHA256 signature of the raw request body. Format: sha256=<64 hex chars>.

​
Verifying the signature

Compute an HMAC-SHA256 digest of the raw request body bytes using your subscription secret, then compare it to the sha256= portion of x-agentrail-signature. Do not parse the JSON body before computing the digest. 
const crypto = require("crypto");

function verifySignature(rawBody, secret, signatureHeader) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}
Always verify the signature before processing a delivery. Reject any delivery where the signature does not match. Respond with 410 to tell AgentRail to disable the subscription if your endpoint is being retired.

​
CLI alternative

You can also manage subscriptions with the AgentRail CLI: 
agentrail event subscribe --url https://agents.example.com/webhooks/task-events \
  --event-types task.updated,task.reviewed,task.shipped

​
Error responses

StatusCodeMeaning
400validation_errorRequest body failed validation.
401unauthorizedBearer token is missing or invalid.
403insufficient_scopeKey does not have webhooks:write (create) or webhooks:read (list).
409conflictAn active subscription already exists for this endpoint and filter set, or the Idempotency-Key was reused with a different body.