How to use webhooks for agent identity events
Subscribe to Leash webhooks to receive signed agent identity, treasury, receipt, and lifecycle events in your own systems.
Why it matters
If your app needs to react when receipts publish, treasuries change, or agent lifecycle events happen, webhooks are the integration surface.
Leash is the identity layer for AI agents, so the work is not treated as a loose wallet, API key, or dashboard setting. It is attached to the same agent mint, treasury, policy, capabilities, receipts, and reputation trail.
How Leash handles it
Leash sends signed webhook deliveries for subscribed events and stores delivery attempts so operators can inspect status and retries.
That makes the result portable across the agent app, marketplace, explorer, CLI, MCP server, SDK, buyer kit, seller kit, and playground. The surface can change, but the identity and proof trail stay the same.
Implementation checklist
Create a subscription, store the secret, verify signatures, handle retries idempotently, and keep event processing separate from user-facing latency.
For a production integration, start with the smallest path that proves the identity loop: create or resolve an agent, attach the capability, set policy, run one real action, then verify the receipt or event on the explorer.
Create a webhook with the SDK
import { LeashClient } from '@leashmarket/sdk';
const leash = new LeashClient({
agentMint: agentMint,
executiveSecretBase58: process.env.LEASH_EXECUTIVE_KEY!,
});
const sub = await leash.createWebhook({
url: 'https://my-app.example/leash-webhook',
events: ['receipt.published', 'agent.treasury.withdraw'],
});
console.log(sub.secret);FAQ
Should webhook handlers be idempotent?
Yes. Delivery retries are expected in distributed systems, so handlers should de-duplicate by event id.
Are webhook signatures optional?
No. Production receivers should verify the signature before trusting the payload.