jackboxpartypack-gamepicker/docs/api/endpoints/webhooks.md

# Webhooks Endpoints

HTTP callback endpoints for external integrations. Register webhook URLs to receive notifications about events like game additions. All endpoints require authentication.

## Endpoint Summary

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/webhooks` | Bearer | List all webhooks |
| GET | `/api/webhooks/{id}` | Bearer | Get single webhook |
| POST | `/api/webhooks` | Bearer | Create webhook |
| PATCH | `/api/webhooks/{id}` | Bearer | Update webhook |
| DELETE | `/api/webhooks/{id}` | Bearer | Delete webhook |
| POST | `/api/webhooks/test/{id}` | Bearer | Send test event |
| GET | `/api/webhooks/{id}/logs` | Bearer | Get webhook delivery logs |

---

## GET /api/webhooks

List all registered webhooks. `secret` is not included in responses. `events` is returned as a parsed array. `enabled` is returned as a boolean.

### Authentication

Bearer token required.

### Response

**200 OK**

```json
[
  {
    "id": 1,
    "name": "Discord Bot",
    "url": "https://example.com/webhook",
    "events": ["game.added"],
    "enabled": true,
    "created_at": "2024-01-15T12:00:00.000Z"
  }
]
```

Note: `secret` is never returned.

### Error Responses

| Status | Body | When |
|--------|------|------|
| 401 | `{ "error": "Access token required" }` | No Bearer token |
| 403 | `{ "error": "Invalid or expired token" }` | Bad or expired token |
| 500 | `{ "error": "..." }` | Server error |

### Example

```bash
curl "http://localhost:5000/api/webhooks" \
  -H "Authorization: Bearer $TOKEN"
```

---

## GET /api/webhooks/{id}

Get a single webhook by ID.

### Authentication

Bearer token required.

### Path Parameters

| Name | Type | Description |
|------|------|-------------|
| id | integer | Webhook ID |

### Response

**200 OK**

```json
{
  "id": 1,
  "name": "Discord Bot",
  "url": "https://example.com/webhook",
  "events": ["game.added"],
  "enabled": true,
  "created_at": "2024-01-15T12:00:00.000Z"
}
```

### Error Responses

| Status | Body | When |
|--------|------|------|
| 404 | `{ "error": "Webhook not found" }` | Invalid ID |

### Example

```bash
curl "http://localhost:5000/api/webhooks/1" \
  -H "Authorization: Bearer $TOKEN"
```

---

## POST /api/webhooks

Create a new webhook.

### Authentication

Bearer token required.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | Display name for the webhook |
| url | string | Yes | Callback URL (must be valid) |
| secret | string | Yes | Secret for signing payloads |
| events | array | Yes | Event types to subscribe to (e.g., `["game.added"]`) |

```json
{
  "name": "Discord Bot",
  "url": "https://example.com/webhook",
  "secret": "mysecret123",
  "events": ["game.added"]
}
```

### Response

**201 Created**

```json
{
  "id": 5,
  "name": "Discord Bot",
  "url": "https://example.com/webhook",
  "events": ["game.added"],
  "enabled": true,
  "created_at": "2024-01-15T12:00:00.000Z",
  "message": "Webhook created successfully"
}
```

### Error Responses

| Status | Body | When |
|--------|------|------|
| 400 | `{ "error": "Missing required fields: name, url, secret, events" }` | Missing fields |
| 400 | `{ "error": "events must be an array" }` | `events` is not an array |
| 400 | `{ "error": "Invalid URL format" }` | URL validation failed |

### Example

```bash
curl -X POST "http://localhost:5000/api/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Discord Bot",
    "url": "https://example.com/webhook",
    "secret": "mysecret123",
    "events": ["game.added"]
  }'
```

---

## PATCH /api/webhooks/{id}

Update an existing webhook. At least one field must be provided.

### Authentication

Bearer token required.

### Path Parameters

| Name | Type | Description |
|------|------|-------------|
| id | integer | Webhook ID |

### Request Body

All fields optional. Include only the fields to update.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | No | Display name |
| url | string | No | Callback URL (must be valid) |
| secret | string | No | New secret |
| events | array | No | Event types (must be array) |
| enabled | boolean | No | Enable or disable the webhook |

```json
{
  "name": "Discord Bot Updated",
  "url": "https://example.com/webhook-v2",
  "enabled": true
}
```

### Response

**200 OK**

```json
{
  "id": 5,
  "name": "Discord Bot Updated",
  "url": "https://example.com/webhook-v2",
  "events": ["game.added"],
  "enabled": true,
  "created_at": "2024-01-15T12:00:00.000Z",
  "message": "Webhook updated successfully"
}
```

### Error Responses

| Status | Body | When |
|--------|------|------|
| 400 | `{ "error": "No fields to update" }` | No fields in body |
| 400 | `{ "error": "Invalid URL format" }` | Invalid URL |
| 400 | `{ "error": "events must be an array" }` | `events` not an array |
| 404 | `{ "error": "Webhook not found" }` | Invalid ID |

### Example

```bash
curl -X PATCH "http://localhost:5000/api/webhooks/5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Discord Bot Updated", "enabled": true}'
```

---

## DELETE /api/webhooks/{id}

Delete a webhook. Cascades to `webhook_logs` (logs are deleted).

### Authentication

Bearer token required.

### Path Parameters

| Name | Type | Description |
|------|------|-------------|
| id | integer | Webhook ID |

### Response

**200 OK**

```json
{
  "message": "Webhook deleted successfully",
  "webhookId": 5
}
```

### Error Responses

| Status | Body | When |
|--------|------|------|
| 404 | `{ "error": "Webhook not found" }` | Invalid ID |

### Example

```bash
curl -X DELETE "http://localhost:5000/api/webhooks/5" \
  -H "Authorization: Bearer $TOKEN"
```

---

## POST /api/webhooks/test/{id}

Send a test `game.added` event with dummy data to the webhook URL. Delivery runs asynchronously; check `webhook_logs` for status.

### Authentication

Bearer token required.

### Path Parameters

| Name | Type | Description |
|------|------|-------------|
| id | integer | Webhook ID |

### Response

**200 OK**

```json
{
  "message": "Test webhook sent",
  "note": "Check webhook_logs table for delivery status"
}
```

### Error Responses

| Status | Body | When |
|--------|------|------|
| 404 | `{ "error": "Webhook not found" }` | Invalid ID |

### Example

```bash
curl -X POST "http://localhost:5000/api/webhooks/test/5" \
  -H "Authorization: Bearer $TOKEN"
```

---

## GET /api/webhooks/{id}/logs

Get delivery logs for a webhook. Payload is parsed from JSON string to object.

### Authentication

Bearer token required.

### Path Parameters

| Name | Type | Description |
|------|------|-------------|
| id | integer | Webhook ID |

### Query Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| limit | query | integer | No | Max number of logs (default: 50) |

### Response

**200 OK**

```json
[
  {
    "id": 1,
    "webhook_id": 5,
    "event_type": "game.added",
    "payload": {
      "session": { "id": 3, "is_active": true, "games_played": 2 },
      "game": {
        "id": 42,
        "title": "Quiplash 3",
        "pack_name": "Jackbox Party Pack 7",
        "min_players": 3,
        "max_players": 8,
        "manually_added": false
      }
    },
    "response_status": 200,
    "error_message": null,
    "created_at": "2024-01-15T12:00:00.000Z"
  }
]
```

### Error Responses

| Status | Body | When |
|--------|------|------|
| 500 | `{ "error": "..." }` | Server error |

### Example

```bash
curl "http://localhost:5000/api/webhooks/5/logs?limit=20" \
  -H "Authorization: Bearer $TOKEN"
```