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
PUT	`/api/schemas/{id}`	Update schema
DELETE	`/api/schemas/{id}`	Delete schema
POST	`/api/schemas/{id}/validate`	Validate a payload against the 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 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
jsonSchema	object	Yes	JSON Schema object (draft-07)
description	string	No	Optional description

Example

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",
    "jsonSchema": {
      "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",
  "jsonSchema": { ... },
  "version": 1,
  "routeCount": 0,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get Schema

GET /api/schemas/{id}

Example

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

Response

Returns the full schema object.

Update Schema

PUT /api/schemas/{id}

Request Body

All fields are optional. Only provided fields are updated.

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

Info

Updating the schema field automatically increments the version number.

Example

curl -X PUT https://api.hookbase.app/api/schemas/sch_abc123 \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonSchema": {
      "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 -X DELETE https://api.hookbase.app/api/schemas/sch_abc123 \
  -H "Authorization: Bearer whr_your_api_key"

Response

204 No Content

Validate a Payload

Test a payload against a saved schema without sending an event. Useful for building and debugging schemas.

POST /api/schemas/{id}/validate

Request Body

Field	Type	Required	Description
payload	object	Yes	The payload to validate

Example

curl -X POST https://api.hookbase.app/api/schemas/sch_abc123/validate \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "payload": { "type": "payment_intent.succeeded", "data": {} } }'

Response

{
  "valid": false,
  "errors": [
    { "path": "data.object", "message": "Required property missing" }
  ],
  "payload": { "type": "payment_intent.succeeded", "data": {} }
}

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

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
PUT	`/api/schemas/{id}`	Update schema
DELETE	`/api/schemas/{id}`	Delete schema
POST	`/api/schemas/{id}/validate`	Validate a payload against the 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 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
jsonSchema	object	Yes	JSON Schema object (draft-07)
description	string	No	Optional description

Example

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",
    "jsonSchema": {
      "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",
  "jsonSchema": { ... },
  "version": 1,
  "routeCount": 0,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get Schema

GET /api/schemas/{id}

Example

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

Response

Returns the full schema object.

Update Schema

PUT /api/schemas/{id}

Request Body

All fields are optional. Only provided fields are updated.

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

Info

Updating the schema field automatically increments the version number.

Example

curl -X PUT https://api.hookbase.app/api/schemas/sch_abc123 \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonSchema": {
      "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 -X DELETE https://api.hookbase.app/api/schemas/sch_abc123 \
  -H "Authorization: Bearer whr_your_api_key"

Response

204 No Content

Validate a Payload

Test a payload against a saved schema without sending an event. Useful for building and debugging schemas.

POST /api/schemas/{id}/validate

Request Body

Field	Type	Required	Description
payload	object	Yes	The payload to validate

Example

curl -X POST https://api.hookbase.app/api/schemas/sch_abc123/validate \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "payload": { "type": "payment_intent.succeeded", "data": {} } }'

Response

{
  "valid": false,
  "errors": [
    { "path": "data.object", "message": "Required property missing" }
  ],
  "payload": { "type": "payment_intent.succeeded", "data": {} }
}

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