Guides

Webhooks

AgentRail emits an event for everything that happens in your account. Subscribe to webhooks to keep your systems in sync.

Overview

AgentRail emits one event for every state change in your account — wallets opened, payments authorized, policies hit, agents paused, disputes filed. Each event is delivered to the webhook URLs you register, signed, and retried until acknowledged.

Subscribing

Register an endpoint in the console under Developers → Webhooks, or via the API:

subscribe.pyPython
await client.webhooks.subscriptions.create(
    url="https://api.yourapp.com/agentrail",
    event_types=["payment.*", "wallet.*", "policy.violation"],
)

Each subscription gets its own signing secret. Rotate it from the console at any time — both old and new secrets are valid for a 24-hour overlap window.

Verifying signatures

Every webhook request carries an AgentRail-Signature header. Verify it before trusting the body.

verify.pyPython
from agentrail import verify_webhook

@app.post("/agentrail")
async def handle(req):
    body = await req.body()
    sig  = req.headers["agentrail-signature"]
    try:
        event = verify_webhook(body, sig, secret=WEBHOOK_SECRET)
    except agentrail.SignatureMismatch:
        return Response(status_code=401)
    # event.type, event.data, event.created_at
    return {"ok": True}
Heads up
Signature verification protects against forged requests and replay attacks. Never trust a webhook body whose signature you haven't checked.

Retries and ordering

  • ─Webhooks are retried with exponential backoff for up to 72 hours.
  • ─Each event carries a stable event_id — use it for idempotency.
  • ─Events within a single agent run are ordered. Events across runs may interleave.
  • ─An HTTP 2xx response acknowledges. Anything else triggers a retry.

Event catalog

A short list of the most useful event types. The full catalog, including payload schemas, lives in the API reference.

  • ─wallet.created · wallet.funded · wallet.frozen
  • ─payment.created · payment.settled · payment.failed
  • ─policy.checked · policy.violation · policy.approval_required
  • ─agent.created · agent.paused · agent.capability_changed
  • ─compliance.screening · compliance.hit
← Back to docs indexAsk AgentRail Chat →