Webhooks
Developer / Webhooks
Beta

Webhooks

Nhận notifications từ IAI Flow khi có events: run completed, run failed, flow updated.

Webhooks hiện đang trong giai đoạn beta. Schema có thể thay đổi.

Webhook Events

EventKhi nào fire
run.completedKhi run kết thúc với status success
run.failedKhi run kết thúc với status failed
run.startedKhi run bắt đầu chạy
flow.updatedKhi flow definition được cập nhật
agent.completedKhi agent task kết thúc

Webhook Payload

POST https://your-endpoint.com/webhook
Content-Type: application/json
X-IAI-Event: run.completed
X-IAI-Signature: sha256=...

{
  "event": "run.completed",
  "timestamp": "2026-01-01T00:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "run_id": "run_...",
    "workflow_id": "wf_...",
    "workflow_name": "My Flow",
    "status": "success",
    "duration_ms": 1240,
    "started_at": "2026-01-01T00:00:00Z",
    "finished_at": "2026-01-01T00:00:01Z"
  }
}

Signature Verification

Mỗi webhook được ký bằng HMAC-SHA256 với webhook secret của workspace.

// Node.js
const crypto = require("crypto");

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

Retry Policy

  • Retry tối đa 3 lần nếu endpoint trả về status ngoài 2xx
  • Backoff: 30s, 5m, 30m
  • Sau 3 lần thất bại, webhook được đánh dấu failed
  • Endpoint phải respond trong 10 giây

Registering Webhooks

Webhook registration API sẽ available trong phiên bản tới. Hiện tại có thể configure qua Settings trong dash.iai.one.

Trigger node: Để nhận external webhooks vào trong flow, dùng node type http_trigger hoặc webhook trong builder.