Chuyển đến nội dung
HILLS API v1

Tham chiếu API

Webhook

Endpoint mà HILLS Music gọi khi có sự kiện: bản phát hành, phân phối, DDEX, sao kê, thanh toán, yêu cầu và Live support. Có chữ ký, có gửi lại.

Endpoint mà HILLS Music gọi khi có sự kiện: bản phát hành, phân phối, DDEX, sao kê, thanh toán, yêu cầu và Live support. Có chữ ký, có gửi lại.

Base URL https://api.hillsmusic.com/v1. Mọi request đều gửi một API key: Authorization: Bearer hm_live_….

  • Liệt kê các loại sự kiện webhook
  • Liệt kê endpoint webhook
  • Tạo endpoint webhook
  • Lấy một endpoint webhook
  • Cập nhật endpoint webhook
  • Xóa endpoint webhook
  • Đổi secret của webhook
  • Gửi sự kiện test
  • Liệt kê các lần gửi của một endpoint
  • Gửi lại một lần gửi

Liệt kê các loại sự kiện webhook

GET /v1/webhooks/events · Scope: webhooks:read hoặc webhooks:write

Mọi loại sự kiện mà một endpoint có thể đăng ký, kèm ý nghĩa. Payload được mô tả trong phần webhooks của tài liệu tham chiếu này.

Ví dụ request

curl "https://api.hillsmusic.com/v1/webhooks/events" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi 200

{
  "data": [
    {
      "type": "release.approved",
      "label": "Release approved",
      "description": "A release was approved and is queued for its stores."
    }
  ]
}

Lỗi

Mã trạng thái Khi nào
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
429 rate_limited: chờ số giây ghi trong Retry-After.

Liệt kê endpoint webhook

GET /v1/webhooks · Scope: webhooks:read hoặc webhooks:write

Các endpoint webhook của bạn (tối đa 20), cũ nhất trước. Secret không bao giờ được liệt kê.

Ví dụ request

curl "https://api.hillsmusic.com/v1/webhooks" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi 200

{
  "data": [
    {
      "id": 7,
      "url": "https://example.com/hills/webhooks",
      "description": "Order system",
      "events": [
        "release.approved",
        "delivery.store_status_changed"
      ],
      "enabled": true,
      "secret_prefix": "whsec_3f9a1c",
      "created_at": "2026-10-13T09:00:00Z",
      "updated_at": "2026-10-13T09:00:00Z",
      "last_success_at": null,
      "last_failure_at": null,
      "failure_count": 0,
      "disabled_at": null,
      "disabled_reason": null
    }
  ]
}

Lỗi

Mã trạng thái Khi nào
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
429 rate_limited: chờ số giây ghi trong Retry-After.

Tạo endpoint webhook

POST /v1/webhooks · Scope: webhooks:write

Đăng ký một URL https cho các sự kiện bạn chọn. Phản hồi chứa secret dùng để ký, chỉ một lần. URL phải công khai: các địa chỉ private, local và metadata bị từ chối.

Body của request

JSON.

Trường Kiểu Bắt buộc Mô tả
url string Có Nơi nhận sự kiện qua POST: một URL https:// công khai trên cổng 443.
description string Không Ghi chú cho bạn, ví dụ hệ thống nhận sự kiện.
events array Có Các loại sự kiện cần gửi (xem Webhook trong tài liệu tham chiếu này).
enabled boolean Không Mặc định true.

Ví dụ request

curl -X POST "https://api.hillsmusic.com/v1/webhooks" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hills/webhooks","description":"Order system","events":["release.approved","delivery.store_status_changed"]}'

Phản hồi 201

{
  "endpoint": {
    "id": 7,
    "url": "https://example.com/hills/webhooks",
    "description": "Order system",
    "events": [
      "release.approved",
      "delivery.store_status_changed"
    ],
    "enabled": true,
    "secret_prefix": "whsec_3f9a1c",
    "created_at": "2026-10-13T09:00:00Z",
    "updated_at": "2026-10-13T09:00:00Z",
    "last_success_at": null,
    "last_failure_at": null,
    "failure_count": 0,
    "disabled_at": null,
    "disabled_reason": null
  },
  "secret": "whsec_3f9a1c0d5e7b2a4c6e8f0a1b3c5d7e9f1a2b3c4d5e6f7a8b"
}

Lỗi

Mã trạng thái Khi nào
400 invalid: một parameter bị sai; field cho biết parameter nào. invalid_url: không phải URL https công khai trên cổng 443.
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
409 too_many: đã có 20 endpoint.
429 rate_limited: chờ số giây ghi trong Retry-After.

Lấy một endpoint webhook

GET /v1/webhooks/{id} · Scope: webhooks:read hoặc webhooks:write

Một endpoint cùng tình trạng hoạt động: lần thành công và thất bại gần nhất, số lần thử thất bại liên tiếp, và lý do bị tắt.

Parameter

Parameter Vị trí Kiểu Bắt buộc Mô tả
id path integer Có Id của endpoint.

Ví dụ request

curl "https://api.hillsmusic.com/v1/webhooks/7" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi 200

{
  "data": {
    "id": 7,
    "url": "https://example.com/hills/webhooks",
    "description": "Order system",
    "events": [
      "release.approved",
      "delivery.store_status_changed"
    ],
    "enabled": true,
    "secret_prefix": "whsec_3f9a1c",
    "created_at": "2026-10-13T09:00:00Z",
    "updated_at": "2026-10-13T09:00:00Z",
    "last_success_at": null,
    "last_failure_at": null,
    "failure_count": 0,
    "disabled_at": null,
    "disabled_reason": null
  }
}

Lỗi

Mã trạng thái Khi nào
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404 not_found: không tồn tại, hoặc không thuộc về bạn.
429 rate_limited: chờ số giây ghi trong Retry-After.

Cập nhật endpoint webhook

PATCH /v1/webhooks/{id} · Scope: webhooks:write

Thay đổi URL, mô tả, sự kiện, hoặc tắt và bật endpoint (enabled). Bật lại sẽ đặt lại số lần thất bại; các lần gửi bị bỏ trong lúc endpoint tắt có thể được gửi lại bằng retry.

Parameter

Parameter Vị trí Kiểu Bắt buộc Mô tả
id path integer Có Id của endpoint.

Body của request

JSON.

Trường Kiểu Bắt buộc Mô tả
url string Không Nơi nhận sự kiện qua POST: một URL https:// công khai trên cổng 443.
description string Không Ghi chú cho bạn, ví dụ hệ thống nhận sự kiện.
events array Không Các loại sự kiện cần gửi (xem Webhook trong tài liệu tham chiếu này).
enabled boolean Không false để tắt; true để bật lại.

Ví dụ request

curl -X PATCH "https://api.hillsmusic.com/v1/webhooks/7" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Phản hồi 200

{
  "data": {
    "id": 7,
    "url": "https://example.com/hills/webhooks",
    "description": "Order system",
    "events": [
      "release.approved",
      "delivery.store_status_changed"
    ],
    "enabled": true,
    "secret_prefix": "whsec_3f9a1c",
    "created_at": "2026-10-13T09:00:00Z",
    "updated_at": "2026-10-13T09:00:00Z",
    "last_success_at": null,
    "last_failure_at": null,
    "failure_count": 0,
    "disabled_at": null,
    "disabled_reason": null
  }
}

Lỗi

Mã trạng thái Khi nào
400 invalid: một parameter bị sai; field cho biết parameter nào. invalid_url: không phải URL https công khai trên cổng 443.
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404 not_found: không tồn tại, hoặc không thuộc về bạn.
429 rate_limited: chờ số giây ghi trong Retry-After.

Xóa endpoint webhook

DELETE /v1/webhooks/{id} · Scope: webhooks:write

Xóa endpoint và nhật ký gửi của nó. Không có gì được gửi đến endpoint này nữa.

Parameter

Parameter Vị trí Kiểu Bắt buộc Mô tả
id path integer Có Id của endpoint.

Ví dụ request

curl -X DELETE "https://api.hillsmusic.com/v1/webhooks/7" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi 200

{
  "ok": true
}

Lỗi

Mã trạng thái Khi nào
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404 not_found: không tồn tại, hoặc không thuộc về bạn.
429 rate_limited: chờ số giây ghi trong Retry-After.

Đổi secret của webhook

POST /v1/webhooks/{id}/roll-secret · Scope: webhooks:write

Tạo secret ký mới; secret cũ ngừng hoạt động ngay lập tức. Secret mới chỉ có trong phản hồi này.

Parameter

Parameter Vị trí Kiểu Bắt buộc Mô tả
id path integer Có Id của endpoint.

Ví dụ request

curl -X POST "https://api.hillsmusic.com/v1/webhooks/7/roll-secret" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi 200

{
  "endpoint": {
    "id": 7,
    "url": "https://example.com/hills/webhooks",
    "description": "Order system",
    "events": [
      "release.approved",
      "delivery.store_status_changed"
    ],
    "enabled": true,
    "secret_prefix": "whsec_3f9a1c",
    "created_at": "2026-10-13T09:00:00Z",
    "updated_at": "2026-10-13T09:00:00Z",
    "last_success_at": null,
    "last_failure_at": null,
    "failure_count": 0,
    "disabled_at": null,
    "disabled_reason": null
  },
  "secret": "whsec_3f9a1c0d5e7b2a4c6e8f0a1b3c5d7e9f1a2b3c4d5e6f7a8b"
}

Lỗi

Mã trạng thái Khi nào
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404 not_found: không tồn tại, hoặc không thuộc về bạn.
429 rate_limited: chờ số giây ghi trong Retry-After.

Gửi sự kiện test

POST /v1/webhooks/{id}/test · Scope: webhooks:write

Đưa một sự kiện webhook.test vào hàng đợi gửi đến endpoint này, bất kể endpoint đăng ký sự kiện nào, có chữ ký như mọi sự kiện khác. Kết quả hiển thị trong danh sách lần gửi.

Parameter

Parameter Vị trí Kiểu Bắt buộc Mô tả
id path integer Có Id của endpoint.

Ví dụ request

curl -X POST "https://api.hillsmusic.com/v1/webhooks/7/test" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi 202

{
  "delivery": {
    "id": 1042,
    "endpoint_id": 7,
    "event": "webhook.test",
    "event_id": "5d0c2b7e-8a43-4c4e-9f1e-2f0b9a6c1d33",
    "attempt": 0,
    "status": "pending",
    "response_status": null,
    "response_ms": null,
    "next_attempt_at": "2026-10-13T09:05:00Z",
    "error": null,
    "created_at": "2026-10-13T09:05:00Z",
    "delivered_at": null,
    "payload": {
      "id": "5d0c2b7e-8a43-4c4e-9f1e-2f0b9a6c1d33",
      "type": "release.approved",
      "api_version": "v1",
      "occurred_at": "2026-10-13T09:05:00Z",
      "account_id": 12,
      "data": {
        "release": {
          "id": 812,
          "title": "Midnight Run"
        }
      }
    }
  }
}

Lỗi

Mã trạng thái Khi nào
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404 not_found: không tồn tại, hoặc không thuộc về bạn.
409 endpoint_disabled: endpoint đang tắt.
429 rate_limited: chờ số giây ghi trong Retry-After.

Liệt kê các lần gửi của một endpoint

GET /v1/webhooks/{id}/deliveries · Scope: webhooks:read hoặc webhooks:write

Những gì đã được gửi đến endpoint trong 30 ngày gần nhất, mới nhất trước: payload, các lần thử, mã trạng thái HTTP và thời điểm gần nhất, và lỗi.

Parameter

Parameter Vị trí Kiểu Bắt buộc Mô tả
id path integer Có Id của endpoint.
status query pending | succeeded | failed Không Chỉ các lần gửi này.
event query string Không Chỉ loại sự kiện này.
limit query number Không 1–100, mặc định 50.
before query number Không Các lần gửi cũ hơn id lần gửi này (trang tiếp theo).

Ví dụ request

curl "https://api.hillsmusic.com/v1/webhooks/7/deliveries?status=failed" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi 200

{
  "data": [
    {
      "id": 1042,
      "endpoint_id": 7,
      "event": "release.approved",
      "event_id": "5d0c2b7e-8a43-4c4e-9f1e-2f0b9a6c1d33",
      "attempt": 1,
      "status": "succeeded",
      "response_status": 200,
      "response_ms": 184,
      "next_attempt_at": "2026-10-13T09:05:00Z",
      "error": null,
      "created_at": "2026-10-13T09:05:00Z",
      "delivered_at": "2026-10-13T09:05:01Z",
      "payload": {
        "id": "5d0c2b7e-8a43-4c4e-9f1e-2f0b9a6c1d33",
        "type": "release.approved",
        "api_version": "v1",
        "occurred_at": "2026-10-13T09:05:00Z",
        "account_id": 12,
        "data": {
          "release": {
            "id": 812,
            "title": "Midnight Run"
          }
        }
      }
    }
  ],
  "has_more": false
}

Lỗi

Mã trạng thái Khi nào
400 invalid: một parameter bị sai; field cho biết parameter nào.
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404 not_found: không tồn tại, hoặc không thuộc về bạn.
429 rate_limited: chờ số giây ghi trong Retry-After.

Gửi lại một lần gửi

POST /v1/webhooks/{id}/deliveries/{delivery_id}/retry · Scope: webhooks:write

Gửi lại ngay cùng sự kiện đó (cùng id và payload) đến endpoint.

Parameter

Parameter Vị trí Kiểu Bắt buộc Mô tả
id path integer Có Id của endpoint.
delivery_id path integer Có Id của lần gửi.

Ví dụ request

curl -X POST "https://api.hillsmusic.com/v1/webhooks/7/deliveries/1042/retry" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi 202

{
  "delivery": {
    "id": 1042,
    "endpoint_id": 7,
    "event": "release.approved",
    "event_id": "5d0c2b7e-8a43-4c4e-9f1e-2f0b9a6c1d33",
    "attempt": 1,
    "status": "pending",
    "response_status": 200,
    "response_ms": 184,
    "next_attempt_at": "2026-10-13T09:05:00Z",
    "error": null,
    "created_at": "2026-10-13T09:05:00Z",
    "delivered_at": "2026-10-13T09:05:01Z",
    "payload": {
      "id": "5d0c2b7e-8a43-4c4e-9f1e-2f0b9a6c1d33",
      "type": "release.approved",
      "api_version": "v1",
      "occurred_at": "2026-10-13T09:05:00Z",
      "account_id": 12,
      "data": {
        "release": {
          "id": 812,
          "title": "Midnight Run"
        }
      }
    }
  }
}

Lỗi

Mã trạng thái Khi nào
401 unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403 insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404 not_found: không tồn tại, hoặc không thuộc về bạn.
409 endpoint_disabled: endpoint đang tắt.
429 rate_limited: chờ số giây ghi trong Retry-After.

Sẵn sàng tích hợp?

Đăng ký quyền truy cập API, chúng tôi sẽ phản hồi bạn trong vòng 1–3 ngày làm việc.

Đăng ký quyền truy cập API So sánh các gói