HookbaseDocs
GuideAPI ReferenceIntegrationsUse CasesCLIMCP
Getting StartedSDK ReferencePortal ComponentsAPI Reference
Get Started

Getting Started

IntroductionQuick StartBest PracticesPipeline Architecture

Core Concepts

SourcesDestinationsRoutes

Advanced Features

TransformsAI TransformsFiltersSchemasDeduplicationCustom DomainsTunnelsCron JobsScheduled Sends

Enterprise Security

OverviewCircuit BreakerFailover DestinationsIP FilteringStatic IP DeliveryNotification ChannelsObservability ExportField EncryptionAudit Logs

Kubernetes

Operator GuideCRD ReferenceHelm Chart

Operations

Plans & LimitsProduction ReadinessTroubleshootingTestingComparison
DocsReceiveGuideSchemas

Schemas

Schemas define and validate the structure of webhook payloads.

Overview

Schemas help you:

  • Document expected webhook payload formats
  • Validate incoming webhooks against a schema
  • Catch malformed payloads early
  • Generate documentation automatically

Creating a Schema

Required Fields

FieldDescription
nameHuman-readable name
schemaJSON Schema definition

Optional Fields

FieldDescription
descriptionOptional description
versionSchema version string

JSON Schema

Hookbase uses JSON Schema for validation. Here's a quick overview:

Basic Types

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "count": { "type": "integer" },
    "price": { "type": "number" },
    "active": { "type": "boolean" },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

Required Fields

{
  "type": "object",
  "required": ["id", "event"],
  "properties": {
    "id": { "type": "string" },
    "event": { "type": "string" },
    "data": { "type": "object" }
  }
}

Nested Objects

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      }
    }
  }
}

Enums

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pending", "active", "completed", "failed"]
    }
  }
}

Examples

GitHub Push Event

{
  "name": "GitHub Push Event",
  "version": "1.0",
  "schema": {
    "type": "object",
    "required": ["ref", "repository", "pusher"],
    "properties": {
      "ref": {
        "type": "string",
        "description": "The full git ref that was pushed"
      },
      "before": {
        "type": "string",
        "description": "SHA of the previous HEAD"
      },
      "after": {
        "type": "string",
        "description": "SHA of the current HEAD"
      },
      "repository": {
        "type": "object",
        "required": ["id", "full_name"],
        "properties": {
          "id": { "type": "integer" },
          "full_name": { "type": "string" }
        }
      },
      "pusher": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string" }
        }
      },
      "commits": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "message": { "type": "string" },
            "author": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "email": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}

Stripe Payment Intent

{
  "name": "Stripe Payment Intent",
  "version": "1.0",
  "schema": {
    "type": "object",
    "required": ["id", "object", "type", "data"],
    "properties": {
      "id": {
        "type": "string",
        "pattern": "^evt_"
      },
      "object": {
        "type": "string",
        "const": "event"
      },
      "type": {
        "type": "string",
        "enum": [
          "payment_intent.succeeded",
          "payment_intent.payment_failed",
          "payment_intent.created"
        ]
      },
      "data": {
        "type": "object",
        "required": ["object"],
        "properties": {
          "object": {
            "type": "object",
            "required": ["id", "amount", "currency"],
            "properties": {
              "id": { "type": "string" },
              "amount": { "type": "integer" },
              "currency": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

API Usage

Create Schema

curl -X POST https://api.hookbase.app/api/schemas \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Event",
    "version": "1.0",
    "schema": {
      "type": "object",
      "required": ["orderId", "status"],
      "properties": {
        "orderId": {"type": "string"},
        "status": {"type": "string", "enum": ["created", "paid", "shipped"]}
      }
    }
  }'

List Schemas

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

Validate Payload

curl -X POST https://api.hookbase.app/api/schemas/{schemaId}/validate \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ord_123",
    "status": "paid"
  }'

Response:

{
  "valid": true,
  "errors": []
}

Or with errors:

{
  "valid": false,
  "errors": [
    {
      "path": "/status",
      "message": "must be one of: created, paid, shipped"
    }
  ]
}

Update Schema

curl -X PATCH https://api.hookbase.app/api/schemas/{schemaId} \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.1",
    "schema": { ... }
  }'

Delete Schema

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

Using Schemas with Sources

Attach a schema to a source for automatic validation:

curl -X PATCH https://api.hookbase.app/api/sources/{sourceId} \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaId": "sch_abc123"
  }'

When validation is enabled:

  • Valid payloads are processed normally
  • Invalid payloads are rejected with a 400 error
  • Validation errors are logged

Best Practices

  1. Start permissive: Use additionalProperties: true to allow extra fields

  2. Version your schemas: Include version numbers for tracking changes

  3. Document fields: Use description property for each field

  4. Test thoroughly: Validate sample payloads before enabling on sources

  5. Handle evolution: Plan for schema changes over time

Common Patterns

Allow Additional Properties

{
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "id": { "type": "string" }
  }
}

Optional with Default

{
  "properties": {
    "count": {
      "type": "integer",
      "default": 0
    }
  }
}

String Formats

{
  "properties": {
    "email": { "type": "string", "format": "email" },
    "url": { "type": "string", "format": "uri" },
    "date": { "type": "string", "format": "date-time" },
    "uuid": { "type": "string", "format": "uuid" }
  }
}

Pattern Validation

{
  "properties": {
    "phone": {
      "type": "string",
      "pattern": "^\\+[1-9]\\d{1,14}$"
    }
  }
}

See Also

  • Schemas API — Full API reference
  • Transforms — Reshape payloads
  • Filters — Conditional delivery
  • Pipeline Architecture — Where schemas fit in the pipeline
PreviousFiltersNextDeduplication

On this page

OverviewCreating a SchemaRequired FieldsOptional FieldsJSON SchemaBasic TypesRequired FieldsNested ObjectsEnumsExamplesGitHub Push EventStripe Payment IntentAPI UsageCreate SchemaList SchemasValidate PayloadUpdate SchemaDelete SchemaUsing Schemas with SourcesBest PracticesCommon PatternsAllow Additional PropertiesOptional with DefaultString FormatsPattern ValidationSee Also