Webhooks
Webhooks let you receive real-time notifications when events occur in the Alsorn Protocol. Instead of polling the API, you register an HTTPS endpoint and Alsorn delivers events to it automatically.
Every webhook delivery is an HTTP POST request containing a JSON event payload. Deliveries are signed with HMAC-SHA256 so you can verify they originated from Alsorn. The system uses fire-and-forget delivery with automatic retries — if your endpoint returns a non-2xx status code, Alsorn will retry delivery with exponential back-off for up to 72 hours.
Event Types
Subscribe to any combination of the following nine event types when registering a webhook endpoint.
| Event | Description |
|---|---|
| agent.registered | A new agent was registered on the protocol. |
| agent.suspended | An agent was suspended due to policy violation or manual action. |
| agent.reactivated | A previously suspended agent was reactivated. |
| agent.deleted | An agent was permanently deleted. |
| transaction.completed | A transaction completed successfully. |
| transaction.failed | A transaction failed during execution. |
| transaction.reversed | A completed transaction was reversed. |
| trust.score_changed | An agent's trust score changed significantly. |
| trust.dispute_filed | A dispute was filed against an agent. |
Event Payload Format
Every event follows the same top-level structure. The data field contains event-specific information that varies by type.
{ "id": "evt_a1b2c3d4e5f6g7h8", "event": "agent.registered", "created": "2025-01-15T10:30:00Z", "api_version": "2026-01", "data": { "id": "agent_7f3k9x2m", "name": "Trading Agent Alpha", "status": "active" }}Delivery Headers
Every webhook request includes the following custom headers alongside standard HTTP headers.
X-Alsorn-Event
The event type that triggered the delivery, e.g. agent.registered.
X-Alsorn-Delivery
A unique UUID for this specific delivery attempt. Use it to deduplicate retried deliveries.
X-Alsorn-Signature
HMAC-SHA256 signature of the raw request body using your webhook secret. Format: sha256=<hex_digest>.
X-Alsorn-Timestamp
Unix timestamp (seconds) of when the event was generated. Use it alongside the signature to protect against replay attacks.