Webhooks

Let Evose proactively notify your business systems: Workflow completed, Agent received a message, knowledge base index ready, etc.

How It Works

Event happens in Evose
    ↓
HTTPS POST to your configured URL
    ↓
Your system returns 2xx → done
Your system returns 5xx / timeout → Evose retries (exponential backoff, up to 5 times)

Register a Webhook

POST /v1/webhooks

{
  "url": "https://your-server.example.com/evose-webhook",
  "events": ["workflow.run.completed", "workflow.run.failed"],
  "secret": "<openssl rand -hex 32>"
}

Field	Description
`url`	Receiver URL, must be HTTPS
`events`	Event types to subscribe
`secret`	For signature verification (required)

Supported Events

Event	Triggered when
`workflow.run.completed`	Workflow run succeeded
`workflow.run.failed`	Workflow run failed
`agent.message.received`	Agent received a user message
`knowledge.document.ready`	Document indexing finished
`knowledge.document.failed`	Document parsing failed
`model.failover.triggered`	LLM Failover triggered
`credit.budget.threshold`	Credit budget threshold hit

Event Structure

POST /your-endpoint
Content-Type: application/json
X-Evose-Signature: sha256=abcdef0123...
X-Evose-Event: workflow.run.completed
X-Evose-Delivery-Id: del-xxx

{
  "event": "workflow.run.completed",
  "delivered_at": "2026-05-08T14:30:00Z",
  "data": {
    "workflow_id": "wf-001",
    "run_id": "run-abc",
    "status": "completed",
    "duration_ms": 3200,
    "outputs": { ... }
  }
}

Signature Verification

Prevent forgery:

import hmac, hashlib
 
body = request.body  # raw bytes
signature = request.headers['X-Evose-Signature'].split('=')[1]
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
 
if not hmac.compare_digest(signature, expected):
    return 403

Retry and Idempotency

Behavior	Description
You return 2xx	Treated as success
You return 4xx	No retry (fix the request format and re-subscribe)
You return 5xx / timeout	Retry 5 times: 30s / 1m / 5m / 30m / 2h
Your receiver is broken	Evose stores failed deliveries for 7 days; you can re-send manually in the UI

Use X-Evose-Delivery-Id for idempotency

Retries carry the same Delivery-Id. Your system should deduplicate accordingly.

List / Delete Webhooks

GET /v1/webhooks
DELETE /v1/webhooks/{id}

View Delivery Records

GET /v1/webhooks/{id}/deliveries?status=failed

Test Trigger

POST /v1/webhooks/{id}/ping

Sends a webhook.test event to verify your receiver is healthy.

API · Webhooks