Webhooks
Webhook configuration for receiving event notifications — coming soon
Planned Feature
Webhook support is planned for Q3 2026. The endpoints and event types documented below represent the planned specification and are subject to change. This API is not yet available.
Webhooks allow you to receive HTTP notifications when specific events occur in your Smart Agents organization. This eliminates the need to poll the API for status changes.
Planned Event Types
The following event types are planned for the initial webhook release:
| Event Type | Description |
|---|---|
agent.created | A new agent was created |
agent.updated | An agent's configuration was changed |
agent.deleted | An agent was deleted |
conversation.completed | A conversation received a response |
credits.low_balance | Organization credit balance fell below the alert threshold |
credits.depleted | Organization credit balance reached zero |
credits.replenished | Credits were purchased or auto-replenished |
user.registered | A new user was registered |
user.deactivated | A user was deactivated |
Planned Endpoints
Create Webhook
Register a new webhook endpoint.
POST /v1/webhooksRequired scope: webhooks:write
Planned request body:
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | The HTTPS URL to receive webhook payloads |
events | string[] | Yes | List of event types to subscribe to |
secret | string | No | Secret used to sign webhook payloads (auto-generated if not provided) |
description | string | No | Description for this webhook |
active | boolean | No | Whether the webhook is active (default: true) |
Planned request example:
curl -X POST https://api.agent.net.ai/v1/webhooks \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.example.com/webhooks/smart-agents",
"events": ["credits.low_balance", "credits.depleted", "conversation.completed"],
"description": "Credit monitoring and conversation tracking"
}'Planned response:
{
"data": {
"id": "wh_01H8X3Y4ZC",
"url": "https://your-app.example.com/webhooks/smart-agents",
"events": ["credits.low_balance", "credits.depleted", "conversation.completed"],
"secret": "whsec_xxxxxxxxxxxxxxxxxxxx",
"active": true,
"created_at": "2026-04-12T10:00:00Z"
}
}List Webhooks
GET /v1/webhooksRequired scope: webhooks:read
Update Webhook
PATCH /v1/webhooks/{webhook_id}Required scope: webhooks:write
Delete Webhook
DELETE /v1/webhooks/{webhook_id}Required scope: webhooks:write
Planned Payload Format
Webhook payloads will be sent as JSON POST requests to your configured URL:
{
"id": "evt_01H8X3Y4ZD",
"type": "credits.low_balance",
"created_at": "2026-04-12T10:00:00Z",
"data": {
"organization_id": "org_abc123",
"balance": 450,
"threshold": 500
}
}Planned Signature Verification
Webhook payloads will include a signature header for verification:
X-SmartAgents-Signature: sha256=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxVerify the signature by computing an HMAC-SHA256 of the raw request body using your webhook secret:
import hmac
import hashlib
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)Planned Retry Policy
Failed webhook deliveries (non-2xx responses or timeouts) will be retried with exponential backoff:
| Attempt | Delay |
|---|---|
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 30 minutes |
| 4th retry | 2 hours |
| 5th retry | 12 hours |
After 5 failed retries, the webhook will be marked as failing. If a webhook fails consistently for 7 days, it will be automatically disabled. You will receive an email notification when a webhook is disabled.
Stay Updated
Sign up for product updates at smart.agent.net.ai to be notified when the Webhooks API becomes available.