Real-Time Events
Webhook Events
Get real-time notifications when things happen in Alfred. Subscribe to events, and we'll POST JSON payloads to your endpoints instantly.
Reference
Event Types
Complete list of webhook events with descriptions and example payloads.
Agent Events (4)
agent.created
Fired when a new agent is created.
Example Payload
{
"id": "evt_d5de32be887a9b82fe75ed48",
"event": "agent.created",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"agent_id": "agt_abc123",
"name": "Customer Support Bot",
"model": "gpt-4o",
"created_by": 42
}
}
agent.deployed
Fired when an agent deploys to production.
Example Payload
{
"id": "evt_774673f7b7336f9d9a32107f",
"event": "agent.deployed",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"agent_id": "agt_abc123",
"name": "Customer Support Bot",
"environment": "production",
"version": 3
}
}
agent.error
Fired when an agent encounters a runtime error.
Example Payload
{
"id": "evt_e5297cd2c84f28f8b91b9bf1",
"event": "agent.error",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"agent_id": "agt_abc123",
"error_type": "rate_limit",
"message": "API rate limit exceeded",
"severity": "warning"
}
}
agent.status_changed
Fired when an agent changes status (online/offline/maintenance).
Example Payload
{
"id": "evt_cf4a88b86f4b7a0c4d99d2df",
"event": "agent.status_changed",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"agent_id": "agt_abc123",
"old_status": "online",
"new_status": "maintenance"
}
}
Call Events (4)
call.started
Fired when a voice call begins.
Example Payload
{
"id": "evt_91b0e108460906bc3a192b2d",
"event": "call.started",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"call_id": "call_xyz789",
"agent_id": "agt_abc123",
"from": "+15551234567",
"to": "+15559876543",
"direction": "inbound"
}
}
call.ended
Fired when a voice call completes, includes duration and summary.
Example Payload
{
"id": "evt_62b9a5830f6c5aee8b29dcfd",
"event": "call.ended",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"call_id": "call_xyz789",
"agent_id": "agt_abc123",
"duration_s": 142,
"end_reason": "completed",
"summary": "Customer inquired about billing. Issue resolved."
}
}
call.transferred
Fired when a call is transferred to another agent or number.
Example Payload
{
"id": "evt_98d4a48e89fab19ab40ddd51",
"event": "call.transferred",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"call_id": "call_xyz789",
"from_agent": "agt_abc123",
"to_number": "+15552223344",
"reason": "escalation"
}
}
call.recorded
Fired when a call recording is available.
Example Payload
{
"id": "evt_0ee8d0065120201843bfaa3f",
"event": "call.recorded",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"call_id": "call_xyz789",
"recording_url": "https://storage.gositeme.com/recordings/call_xyz789.mp3",
"duration_s": 142
}
}
Fleet Events (4)
fleet.deployed
Fired when a fleet configuration is deployed.
Example Payload
{
"id": "evt_b66651c71ca4efb8ce901225",
"event": "fleet.deployed",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"fleet_id": "flt_001",
"name": "Support Fleet",
"agent_count": 5,
"version": 2
}
}
fleet.alert
Fired on fleet-level alerts (capacity, errors, performance).
Example Payload
{
"id": "evt_2f869a37ee09f78f6b2d040a",
"event": "fleet.alert",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"fleet_id": "flt_001",
"alert_type": "high_error_rate",
"message": "Error rate exceeded 5% threshold",
"severity": "critical"
}
}
fleet.agent_joined
Fired when an agent is added to a fleet.
Example Payload
{
"id": "evt_da81900a41de5febebe313c6",
"event": "fleet.agent_joined",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"fleet_id": "flt_001",
"agent_id": "agt_abc123"
}
}
fleet.agent_left
Fired when an agent is removed from a fleet.
Example Payload
{
"id": "evt_689e815d68792aaefba5f75c",
"event": "fleet.agent_left",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"fleet_id": "flt_001",
"agent_id": "agt_abc123",
"reason": "removed"
}
}
Tool Events (3)
tool.executed
Fired when an agent executes a tool.
Example Payload
{
"id": "evt_96c2401c55fcdafbf2af7c8f",
"event": "tool.executed",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"tool_id": "weather_lookup",
"agent_id": "agt_abc123",
"duration_ms": 320,
"success": true
}
}
tool.error
Fired when a tool execution fails.
Example Payload
{
"id": "evt_312ad0fb2e4a2ebfb3157c01",
"event": "tool.error",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"tool_id": "weather_lookup",
"agent_id": "agt_abc123",
"error": "Upstream API timeout"
}
}
tool.rate_limited
Fired when a tool call is rate-limited.
Example Payload
{
"id": "evt_daac8d097ba99d339cce6f75",
"event": "tool.rate_limited",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"tool_id": "weather_lookup",
"agent_id": "agt_abc123",
"limit": 100,
"window": "1m"
}
}
Marketplace Events (3)
marketplace.published
Fired when you publish an extension to the marketplace.
Example Payload
{
"id": "evt_8ac6a685891039546832d297",
"event": "marketplace.published",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"extension_id": "ext_555",
"name": "My Custom Tool",
"version": "1.0.0"
}
}
marketplace.purchased
Fired when someone purchases your marketplace extension.
Example Payload
{
"id": "evt_2a5ee6b0f0aa204311965291",
"event": "marketplace.purchased",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"extension_id": "ext_555",
"buyer_id": 99,
"price": 9.99,
"currency": "USD"
}
}
marketplace.review
Fired when your extension receives a review.
Example Payload
{
"id": "evt_3df8f7131f7cc5a7f31fd5c5",
"event": "marketplace.review",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"extension_id": "ext_555",
"rating": 5,
"review": "Great tool!"
}
}
Billing Events (3)
billing.payment_succeeded
Fired on successful payment processing.
Example Payload
{
"id": "evt_eeaf778083bea16bc9650e95",
"event": "billing.payment_succeeded",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"invoice_id": "inv_12345",
"amount": 49,
"currency": "USD"
}
}
billing.payment_failed
Fired when a payment attempt fails.
Example Payload
{
"id": "evt_cfd27986eb7f891798efa5e8",
"event": "billing.payment_failed",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"invoice_id": "inv_12345",
"amount": 49,
"reason": "card_declined"
}
}
billing.usage_alert
Fired when usage approaches or exceeds thresholds.
Example Payload
{
"id": "evt_22b468b406512fa0ec9fab33",
"event": "billing.usage_alert",
"timestamp": "2026-03-04T12:00:00+00:00",
"data": {
"resource": "api_calls",
"current": 9500,
"limit": 10000,
"percentage": 95
}
}
Security
Signature Verification
Every webhook includes an X-Alfred-Signature header. Verify it to ensure authenticity.
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// Express middleware
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const sig = req.headers['x-alfred-signature'];
if (!verifyWebhookSignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body);
console.log('Event:', event.event, event.data);
res.status(200).send('OK');
});import hmac, hashlib
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
expected = 'sha256=' + hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
# Flask example
from flask import Flask, request, abort
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def webhook():
sig = request.headers.get('X-Alfred-Signature', '')
if not verify_signature(request.data, sig, WEBHOOK_SECRET):
abort(401)
event = request.json
print(f"Event: {event['event']}", event['data'])
return 'OK', 200<?php
function verifySignature(string $payload, string $signature, string $secret): bool {
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
return hash_equals($expected, $signature);
}
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ALFRED_SIGNATURE'] ?? '';
$secret = getenv('WEBHOOK_SECRET');
if (!verifySignature($payload, $signature, $secret)) {
http_response_code(401);
die('Invalid signature');
}
$event = json_decode($payload, true);
error_log("Event: " . $event['event']);
http_response_code(200);
echo 'OK';Start Building with Webhooks
Create a free Alfred account to register webhook endpoints and start receiving real-time event notifications.
Get Started Free
Someone from somewhere
just launched website.com
Just now