# 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.

<!-- Generated from openapi/hills-v1.json by scripts/api-reference.mjs. Edit the operation in hills-music (server/lib/ops), not this page. -->

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

<a id="list-webhook-event-types"></a>

## 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

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

### Phản hồi `200`

```json
{
  "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. |

<a id="list-webhook-endpoints"></a>

## 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

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

### Phản hồi `200`

```json
{
  "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. |

<a id="create-a-webhook-endpoint"></a>

## 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

```bash
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`

```json
{
  "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. |

<a id="get-a-webhook-endpoint"></a>

## 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

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

### Phản hồi `200`

```json
{
  "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. |

<a id="update-a-webhook-endpoint"></a>

## 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

```bash
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`

```json
{
  "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. |

<a id="delete-a-webhook-endpoint"></a>

## 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

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

### Phản hồi `200`

```json
{
  "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. |

<a id="roll-a-webhook-secret"></a>

## Đổ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

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

### Phản hồi `200`

```json
{
  "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. |

<a id="send-a-test-event"></a>

## 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

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

### Phản hồi `202`

```json
{
  "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. |

<a id="list-an-endpoints-deliveries"></a>

## 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

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

### Phản hồi `200`

```json
{
  "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. |

<a id="retry-a-delivery"></a>

## 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

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

### Phản hồi `202`

```json
{
  "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. |

Nguồn: https://developer.hillsmusic.com/vi/reference/webhooks/