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

[
  {
    "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

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

{
  "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

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"])

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

Response

201 Created

{
  "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

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

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

Response

200 OK

{
  "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

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

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

Error Responses

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

Example

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

{
  "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

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

[
  {
    "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

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