AiVideoEditor
Bắt đầu miễn phí
Trình đơn

Đã xem lại 2026-11-11 · Phiên bản API 2026-11-09 · Đọc Markdown

Webhook của khách hàng

Gửi sự kiện đi ra cho không gian làm việc của bạn. Đăng ký một endpoint HTTPS, xác minh bí mật ký dùng một lần, và nhận các sự kiện đã ký với số lần thử lại có giới hạn.

Đăng ký endpoint

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • Bí mật ký (whsec_…) chỉ được trả về một lần: trong phản hồi tạo thành công đầu tiên. Hãy lưu nó; việc phát lại idempotent của cùng lần tạo trả về endpoint mà không có bí mật, và nó không thể được hiển thị lại.
  • Điểm đến phải là HTTPS, phân giải được công khai, và không chứa thông tin xác thực nhúng. Các yêu cầu đến địa chỉ riêng tư, loopback, link-local (bao gồm siêu dữ liệu cloud), unique-local và multicast bị từ chối trước khi bất kỳ kết nối nào được tạo, và các chuyển hướng không bao giờ được đi theo.
  • Việc đăng ký đưa một sự kiện webhook.verification có đích đến vào hàng đợi cho endpoint đó, độc lập với bộ lọc eventTypes của nó. Các sự kiện thông thường chỉ chảy sau khi endpoint của bạn trả lời việc xác minh bằng 2xx.

Xác minh các lượt gửi

Mọi yêu cầu đều mang:

HeaderÝ nghĩa
x-publisher-event-idID sự kiện ổn định: giống hệt qua các lần thử lại và phát lại
x-publisher-event-typeLoại sự kiện, ví dụ post.published
x-publisher-timestampGiây Unix
x-publisher-signaturet=<ts>,v1=<hex>

Chữ ký là HMAC-SHA256 trên ${t}.${event_id}.${raw_body} bằng bí mật ký của bạn. Xác minh với dung sai ±300 giây và từ chối các lần phát lại ngoài khoảng đó. Ví dụ Node:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Luôn xác minh với phần thân yêu cầu gốc trước khi phân tích.

Phong bì sự kiện

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

Danh mục sự kiện ban đầu (có thể mở rộng; eventTypes lọc khi đăng ký):

  • webhook.verification: dữ liệu thử thách; trả lời 2xx để kích hoạt endpoint
  • post.published: một điểm đến đã được xác nhận với biên nhận gốc
  • delivery.failed: một điểm đến thất bại hoàn toàn
  • delivery.requires_action: cần đồng ý/kết nối lại/xem xét muộn

Các kết quả tổng hợp của bài đăng (post.partially_published, post.failed) chưa được phát; chúng chỉ được ghi tài liệu tại đây khi đã có một bên sản xuất, nên đừng trông chờ vào chúng. Đăng ký các sự kiện theo điểm đến ở trên và suy ra trạng thái lô từ kết quả gửi của bài đăng.

Thử lại, phát lại và vô hiệu hóa

  • Các lần thử: ngay lập tức, sau đó +1m, +5m, +30m, +2h, +8h. Các lần thử lại dùng lại cùng ID sự kiện và phần thân giống hệt từng byte để bạn có thể khử trùng lặp một cách an toàn.
  • 2xx = đã gửi. 429/5xx/hết thời gian chờ được thử lại. Các mã 4xx khác thất bại vĩnh viễn với sự kiện đó (sửa endpoint rồi phát lại).
  • 410 Gone vô hiệu hóa endpoint: không có sự kiện nào khác được đưa vào hàng đợi cho nó.
  • Phát lại do người vận hành cho phép qua dịch vụ webhook nội bộ gửi lại một sự kiện với ID gốc của nó. Một lần thử đang thực hiện đang được thuê hoạt động không bao giờ bị tước; phát lại báo rằng sự kiện đang bận và có thể thử lại ngay sau đó.

Ghi chú vận hành

  • Chẩn đoán gửi chỉ lưu các mã kết quả an toàn: không bao giờ là bí mật, chữ ký, header yêu cầu hay phần thân phản hồi của bạn. Dữ liệu tải được làm sạch thêm: bí mật của nhà cung cấp/OAuth và URL pre-sign của media bị loại bỏ trước khi bất kỳ thứ gì được đưa vào hàng đợi.
  • Các endpoint thuộc phạm vi không gian làm việc: việc sở hữu UUID endpoint của không gian làm việc khác không có tác dụng gì.
  • Việc gửi là ít nhất một lần cho mỗi lần xuất hiện sự kiện được chấp nhận; khử trùng lặp trên x-publisher-event-id.

Tính khả dụng của công cụ dành cho nhà phát triển

Trang Developers liệt kê khóa API và các endpoint webhook của không gian làm việc một cách độc lập với cấu hình mã hóa bí mật ký. Việc tạo webhook đòi hỏi cấu hình mã hóa máy chủ hợp lệ; hãy nhờ người vận hành triển khai giải quyết cảnh báo cấu hình. Quản lý khóa API vẫn khả dụng. Các bí mật ký hiện có không bao giờ được hiển thị lại.