Webhooks API

Manage webhook subscriptions for your tenant. Requires Business tier or above. For implementation guidance, see the Webhooks Guide.

Available Events

Event	Description
`user.created`	A new user registered in your tenant
`user.updated`	User profile was updated
`user.deleted`	User was deleted
`puzzle.started`	A user started a puzzle
`puzzle.completed`	A user completed a puzzle
`achievement.unlocked`	User unlocked an achievement
`subscription.created`	New subscription started
`subscription.cancelled`	Subscription cancelled
`subscription.renewed`	Subscription renewed

GET/api/v1/webhooks

List Webhooks

Returns all webhook subscriptions for your tenant.

POST/api/v1/webhooks

Create Webhook

bash

curl -X POST "https://api.puzzlesection.app/api/v1/webhooks" \
  -H "X-API-Key: ps_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/puzzle-section",
    "events": ["puzzle.completed", "user.created"],
    "description": "Production webhook"
  }'

Response `201`

JSON

{
  "id": "wh-uuid",
  "url": "https://your-server.com/webhooks/puzzle-section",
  "events": ["puzzle.completed", "user.created"],
  "secret": "whsec_generated_secret",
  "isActive": true,
  "description": "Production webhook",
  "createdAt": "2026-03-05T10:30:00Z"
}

PATCH/api/v1/webhooks/:webhookId

Update Webhook

Update URL, events, secret, description, or active status.

DELETE/api/v1/webhooks/:webhookId

Delete Webhook

Permanently remove a webhook subscription.

POST/api/v1/webhooks/:webhookId/test

Test Webhook

Send a test event to verify your endpoint. Returns delivery status and response time.

JSON

{
  "success": true,
  "statusCode": 200,
  "responseTime": 145
}

GET/api/v1/webhooks/:webhookId/deliveries

List Deliveries

View delivery history for a webhook with optional filters on status, event type, and pagination.