#Webhooks API

Subscribe to platform events via Webhooks for real-time notifications and integrations.

Base Path: /v1/webhooks

#Webhook Management

#Create Webhook

CopyPOST /v1/webhooks

Required Permission: webhooks:create

#Request Body

jsonCopy{
  "url": "https://your-server.com/webhook",
  "events": [
    "agent.created",
    "agent.updated",
    "agent.deleted",
    "document.uploaded",
    "document.processed",
    "document.deleted",
    "knowledge_base.created",
    "knowledge_base.updated",
    "knowledge_base.deleted"
  ],
  "secret": "your-webhook-secret",
  "active": true
}

#Response

CopyHTTP 201 Created

#List Webhooks

CopyGET /v1/webhooks

Required Permission: webhooks:read

#Response

jsonCopy{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://your-server.com/webhook",
      "events": ["agent.created", "agent.updated"],
      "active": true,
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-15T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

#Get Webhook Details

CopyGET /v1/webhooks/:id

Required Permission: webhooks:read

#Update Webhook

CopyPUT /v1/webhooks/:id

Required Permission: webhooks:update

#Request Body

jsonCopy{
  "url": "https://new-server.com/webhook",
  "events": ["agent.created"],
  "active": false
}

#Delete Webhook

CopyDELETE /v1/webhooks/:id

Required Permission: webhooks:delete

#Response

CopyHTTP 204 No Content

#Delivery Management

#Get Delivery History

CopyGET /v1/webhooks/:id/deliveries

Required Permission: webhooks:read

#Query Parameters

#Response

jsonCopy{
  "data": [
    {
      "id": "delivery_xxx",
      "webhookId": "wh_abc123",
      "event": "agent.created",
      "status": "success",
      "statusCode": 200,
      "payload": { "agent": { "id": "agent_xxx", "name": "..." } },
      "response": "OK",
      "duration": 250,
      "attemptCount": 1,
      "createdAt": "2026-02-20T08:00:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

#Get Delivery Statistics

CopyGET /v1/webhooks/:id/deliveries/stats

Required Permission: webhooks:read

#Response

jsonCopy{
  "total": 150,
  "successful": 145,
  "failed": 5,
  "successRate": 96.67,
  "avgDuration": 180
}

#Supported Events

#Agent Events

#Chat / Session Events

#Knowledge Base Events

#Document Events

#Skill Events

#Auth Events

#Billing Events

#Import Job Events

#Webhook Payload Format

When an event is triggered, the system sends a POST request to the registered URL:

CopyPOST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=...

jsonCopy{
  "event": "agent.created",
  "timestamp": "2026-02-20T08:00:00Z",
  "data": {
    "agent": {
      "id": "agent_xxx",
      "name": "New Assistant",
      "model": "zhipu/glm-4"
    }
  }
}

#Signature Verification

If a secret was provided when creating the Webhook, each delivery will include an X-Webhook-Signature header, signed using the HMAC-SHA256 algorithm.

Verification example (Node.js):

javascriptCopyconst crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

#Retry Policy

When a Webhook delivery fails (HTTP status >= 400 or timeout), the system retries with the following strategy:

• 1st retry: 1 minute delay
• 2nd retry: 5 minute delay
• 3rd retry: 30 minute delay

After 3 failed retries, the delivery is marked as failed. Details can be viewed via the delivery history endpoint.