Webhooks

Khả dụng

Sự kiện nền tảng gửi tới hệ thống của bạn, có chữ ký, thử lại và dead-letter.

Webhook là công dân hạng nhất của PORO: mọi capability đều phát event, mọi event đều gửi được tới hệ thống của bạn. Bảo đảm giao nhận là at-least-once — hãy khử trùng lặp theo id event.

Đăng ký điểm nhận

POST /api/public/v1/webhook-endpoints
X-Poro-Key: poro_<prefix>_<secret>
Content-Type: application/json

{
  "url": "https://example.com/poro/webhook",
  "event_types": ["order.created", "inventory.committed"],
  "description": "OMS production"
}

Phản hồi trả về trường secret (whsec_…) đúng một lần. Lưu lại ngay — dùng để xác minh chữ ký.

Gói tin PORO gửi

{
  "id": "evt_4f1c...",
  "type": "order.created",
  "api_version": "2026-09-01",
  "created_at": "2026-09-08T10:30:00Z",
  "org_id": "22222222-...",
  "livemode": true,
  "data": { "object": { "id": "ord_123", "amount": 480000 } }
}

Header

Header	Ý nghĩa
poro-signature	t=<unix>,v1=<hmac-sha256 hex của `t.body`>
poro-event-id	Mã sự kiện, dùng để khử trùng lặp
poro-event-type	Loại sự kiện
poro-delivery-attempt	Lần gửi thứ mấy

Xác minh chữ ký

import { PoroClient } from "@poroai/sdk";

const event = await poro.webhooks.constructEvent(
  rawBody,                                   // body dạng chuỗi, chưa parse
  request.headers.get("poro-signature")!,
  process.env.PORO_WEBHOOK_SECRET!,
);

Thử lại và dead-letter

Coi là thành công khi endpoint trả HTTP 2xx trong 5 giây.
Thử lại tối đa 8 lần theo backoff: 10 giây · 30 giây · 2 phút · 10 phút · 1 giờ · 3 giờ · 6 giờ · 12 giờ.
Hết lượt thử, lượt gửi chuyển sang dead-letter và vẫn xem lại được trong Console.
Lỗi liên tiếp 50 lần, điểm nhận tự tắt để bảo vệ hệ thống của bạn.

Danh mục sự kiện

inventory.reserved · inventory.released · inventory.committed · inventory.updated
order.created · order.paid · order.cancelled · order.fulfilled
catalog.updated · catalog.sync.completed · catalog.sync.failed
stream.created · stream.started · stream.ended · stream.failed
ai.job.created · ai.job.completed · ai.job.failed