sangtao.ai
API key

Webhook

Tạo endpoint

Đăng ký một URL để nhận sự kiện. Trả về secret ký, chỉ một lần.

POSThttps://api.sangtao.ai/v2/webhooks

Xác thực

  • X-Api-Keystring · headerbắt buộc

    API key của bạn, tạo ở trang API key trong tài khoản.

Sự kiện, chữ ký và cách thử lại: Webhook.

Body

  • urlstringbắt buộc

    URL https công khai, cổng 443, không kèm tài khoản / mật khẩu. Tối đa 500 ký tự

  • eventsstring[]bắt buộc

    Các loại sự kiện muốn nhận, hoặc ["*"] để nhận tất cả

    Giá trị có thể:*image.completedimage.failedvideo.completedvideo.failedpost.publishedpost.failedsocial_account.needs_attention

  • descriptionstring

    Ghi chú cho bạn. Tối đa 200 ký tự

Response

  • idstringbắt buộc

    Mã endpoint, whk_…

  • urlstringbắt buộc

    Nơi nhận sự kiện

  • eventsstring[]bắt buộc

    Các loại sự kiện endpoint nhận. ["*"] là tất cả

  • descriptionstring | null

    Ghi chú của bạn

  • enabledbooleanbắt buộc

    Có đang gửi sự kiện tới endpoint không

  • statusstringbắt buộc

    disabled_failing: tự tắt sau 3 ngày giao hỏng liên tục

    Giá trị có thể:activedisableddisabled_failing

  • createdAtstringbắt buộc

    Lúc tạo (ISO 8601, UTC). Endpoint chỉ nhận sự kiện xảy ra từ lúc này

  • lastDeliveryAtstring | null

    Lần gần nhất thử giao tới endpoint

  • lastSuccessAtstring | null

    Lần gần nhất endpoint trả 2xx

  • lastFailureAtstring | null

    Lần gần nhất giao hỏng

  • secretstringbắt buộc

    whsec_… — chỉ hiện ở response này. Hãy lưu lại: dùng để kiểm chữ ký mọi lần giao

Secret chỉ hiện một lần. Mất thì xoay secret mới.

Mã lỗi

MãerrorCodeKhi nào
422INVALID_WEBHOOK_URLurl không phải URL https công khai cổng 443, hoặc có kèm tài khoản / mật khẩu
422INVALID_WEBHOOK_EVENTevents trống hoặc có loại không tồn tại — các loại hợp lệ ở details[0].params.allowed
422VALIDATION_ERRORdescription dài quá 200 ký tự
422WEBHOOK_LIMIT_REACHEDBạn đã có 10 endpoint
POST/webhooks
curl -X POST "https://api.sangtao.ai/v2/webhooks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/sangtao",
    "events": [
      "image.completed",
      "image.failed"
    ],
    "description": "Production"
  }'
{
  "success": true,
  "data": {
    "id": "whk_4nP8rT2xK",
    "url": "https://example.com/webhooks/sangtao",
    "events": [
      "image.completed",
      "image.failed"
    ],
    "description": "Production",
    "enabled": true,
    "status": "active",
    "createdAt": "2026-11-10T08:00:00Z",
    "lastDeliveryAt": null,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "secret": "whsec_Zx3…"
  }
}