Schemas API

Schemas define the expected structure of webhook payloads using JSON Schema. Attach schemas to routes to validate incoming events before delivery.

Endpoints

Method	Path	Description
GET	`/api/schemas`	List schemas
POST	`/api/schemas`	Create schema
GET	`/api/schemas/{id}`	Get schema
PATCH	`/api/schemas/{id}`	Update schema
DELETE	`/api/schemas/{id}`	Delete schema

Schema Object

{
  "id": "sch_abc123",
  "name": "GitHub Push Event",
  "description": "Validates GitHub push webhook payloads",
  "schema": {
    "type": "object",
    "required": ["ref", "repository", "pusher"],
    "properties": {
      "ref": { "type": "string" },
      "repository": {
        "type": "object",
        "required": ["full_name"],
        "properties": {
          "full_name": { "type": "string" }
        }
      },
      "pusher": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string" }
        }
      }
    }
  },
  "version": 1,
  "routeCount": 2,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

List Schemas

GET /api/schemas

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 20, max: 100)
search	string	Search by name

Example

curl

curl https://api.hookbase.app/api/schemas \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "data": [
    {
      "id": "sch_abc123",
      "name": "GitHub Push Event",
      "version": 1,
      "routeCount": 2,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "pageSize": 20
  }
}

Create Schema

POST /api/schemas

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
schema	object	Yes	JSON Schema object (draft-07)
description	string	No	Optional description

Example

curl

curl -X POST https://api.hookbase.app/api/schemas \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Payment Event",
    "description": "Validates Stripe payment_intent webhooks",
    "schema": {
      "type": "object",
      "required": ["type", "data"],
      "properties": {
        "type": {
          "type": "string",
          "pattern": "^payment_intent\\."
        },
        "data": {
          "type": "object",
          "required": ["object"],
          "properties": {
            "object": {
              "type": "object",
              "required": ["id", "amount", "currency"],
              "properties": {
                "id": { "type": "string" },
                "amount": { "type": "integer", "minimum": 0 },
                "currency": { "type": "string", "minLength": 3, "maxLength": 3 }
              }
            }
          }
        }
      }
    }
  }'

Response

{
  "id": "sch_new123",
  "name": "Stripe Payment Event",
  "description": "Validates Stripe payment_intent webhooks",
  "schema": { ... },
  "version": 1,
  "routeCount": 0,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get Schema

GET /api/schemas/{id}

Example

curl

curl https://api.hookbase.app/api/schemas/sch_abc123 \
  -H "Authorization: Bearer whr_your_api_key"

Response

Returns the full schema object.

Update Schema

PATCH /api/schemas/{id}

Request Body

All fields are optional. Only provided fields are updated.

Field	Type	Description
name	string	Display name
schema	object	JSON Schema object
description	string	Optional description

Info

Updating the schema field automatically increments the version number.

Example

curl

curl -X PATCH https://api.hookbase.app/api/schemas/sch_abc123 \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "type": "object",
      "required": ["ref", "repository", "pusher", "commits"],
      "properties": {
        "ref": { "type": "string" },
        "commits": { "type": "array", "minItems": 1 }
      }
    }
  }'

Response

Returns the updated schema object with incremented version.

Delete Schema

DELETE /api/schemas/{id}

Warning

A schema cannot be deleted while it is assigned to active routes. Remove it from all routes first.

Example

curl

curl -X DELETE https://api.hookbase.app/api/schemas/sch_abc123 \
  -H "Authorization: Bearer whr_your_api_key"

Response

204 No Content

Schema Validation Behavior

When a schema is attached to a route:

Incoming event payloads are validated against the JSON Schema
Valid payloads proceed through the route normally
Invalid payloads result in deliveries with status schema_failed
Validation errors are recorded on the delivery for debugging

Viewing Validation Errors

Check the delivery detail for schema validation errors:

{
  "id": "dlv_abc123",
  "status": "schema_failed",
  "error": "Schema validation failed: /data/object/amount must be integer, got string",
  "schemaId": "sch_abc123",
  "schemaVersion": 1
}

Error Responses

400 Bad Request

Invalid JSON Schema:

{
  "error": "Bad Request",
  "message": "Invalid JSON Schema: 'type' must be a valid JSON Schema type",
  "code": "INVALID_SCHEMA"
}

409 Conflict

Schema in use:

{
  "error": "Conflict",
  "message": "Schema is assigned to 2 active routes",
  "code": "RESOURCE_IN_USE"
}

Schemas Guide — Concepts and usage patterns
Routes API — Assign schemas to routes