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

json

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

http

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

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/schemas', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/schemas',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Response

json

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

http

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

curlJavaScriptPython

bash

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 }
              }
            }
          }
        }
      }
    }
  }'

javascript

const response = await fetch('https://api.hookbase.app/api/schemas', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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 }
              }
            }
          }
        }
      }
    }
  })
});
const data = await response.json();

python

import requests

response = requests.post(
  'https://api.hookbase.app/api/schemas',
  headers={
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  json={
    '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 }
              }
            }
          }
        }
      }
    }
  }
)
data = response.json()

Response

json

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

http

GET /api/schemas/{id}

Example

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/schemas/sch_abc123', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/schemas/sch_abc123',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Response

Returns the full schema object.

Update Schema

http

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

curlJavaScriptPython

bash

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 }
      }
    }
  }'

javascript

const response = await fetch('https://api.hookbase.app/api/schemas/sch_abc123', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    schema: {
      type: 'object',
      required: ['ref', 'repository', 'pusher', 'commits'],
      properties: {
        ref: { type: 'string' },
        commits: { type: 'array', minItems: 1 }
      }
    }
  })
});
const data = await response.json();

python

import requests

response = requests.patch(
  'https://api.hookbase.app/api/schemas/sch_abc123',
  headers={
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  json={
    'schema': {
      'type': 'object',
      'required': ['ref', 'repository', 'pusher', 'commits'],
      'properties': {
        'ref': { 'type': 'string' },
        'commits': { 'type': 'array', 'minItems': 1 }
      }
    }
  }
)
data = response.json()

Response

Returns the updated schema object with incremented version.

Delete Schema

http

DELETE /api/schemas/{id}

WARNING

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

Example

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/schemas/sch_abc123', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});

python

import requests

response = requests.delete(
  'https://api.hookbase.app/api/schemas/sch_abc123',
  headers={'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:

json

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

json

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

409 Conflict

Schema in use:

json

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

Endpoints ​

Schema Object ​

List Schemas ​

Query Parameters ​

Example ​

Response ​

Create Schema ​

Request Body ​

Example ​

Response ​

Get Schema ​

Example ​

Response ​

Update Schema ​

Request Body ​

Example ​

Response ​

Delete Schema ​

Example ​

Response ​

Schema Validation Behavior ​

Viewing Validation Errors ​

Error Responses ​

400 Bad Request ​

409 Conflict ​

Related ​

Schemas API

Endpoints

Schema Object

List Schemas

Query Parameters

Example

Response

Create Schema

Request Body

Example

Response

Get Schema

Example

Response

Update Schema

Request Body

Example

Response

Delete Schema

Example

Response

Schema Validation Behavior

Viewing Validation Errors

Error Responses

400 Bad Request

409 Conflict

Related