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

Field	Description
`name`	Human-readable name
`schema`	JSON Schema definition

Optional Fields

Field	Description
`description`	Optional description
`version`	Schema version string

JSON Schema

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

Basic Types

json

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

Required Fields

json

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

Nested Objects

json

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

Enums

json

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

Examples

GitHub Push Event

json

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

json

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

bash

curl -X POST https://api.webhookrelay.com/api/organizations/{orgId}/schemas \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -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

bash

curl https://api.webhookrelay.com/api/organizations/{orgId}/schemas \
  -H "Authorization: Bearer YOUR_TOKEN"

Validate Payload

bash

curl -X POST https://api.webhookrelay.com/api/organizations/{orgId}/schemas/{schemaId}/validate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ord_123",
    "status": "paid"
  }'

Response:

json

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

Or with errors:

json

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

Update Schema

bash

curl -X PATCH https://api.webhookrelay.com/api/organizations/{orgId}/schemas/{schemaId} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.1",
    "schema": { ... }
  }'

Delete Schema

bash

curl -X DELETE https://api.webhookrelay.com/api/organizations/{orgId}/schemas/{schemaId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Using Schemas with Sources

Attach a schema to a source for automatic validation:

bash

curl -X PATCH https://api.webhookrelay.com/api/organizations/{orgId}/sources/{sourceId} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -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

Start permissive: Use additionalProperties: true to allow extra fields
Version your schemas: Include version numbers for tracking changes
Document fields: Use description property for each field
Test thoroughly: Validate sample payloads before enabling on sources
Handle evolution: Plan for schema changes over time

Common Patterns

Allow Additional Properties

json

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

Optional with Default

json

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

String Formats

json

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

Pattern Validation

json

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

Schemas ​

Overview ​

Creating a Schema ​

Required Fields ​

Optional Fields ​

JSON Schema ​

Basic Types ​

Required Fields ​

Nested Objects ​

Enums ​

Examples ​

GitHub Push Event ​

Stripe Payment Intent ​

API Usage ​

Create Schema ​

List Schemas ​

Validate Payload ​

Update Schema ​

Delete Schema ​

Using Schemas with Sources ​

Best Practices ​

Common Patterns ​

Allow Additional Properties ​

Optional with Default ​

String Formats ​

Pattern Validation ​

Schemas

Overview

Creating a Schema

Required Fields

Optional Fields

JSON Schema

Basic Types

Required Fields

Nested Objects

Enums

Examples

GitHub Push Event

Stripe Payment Intent

API Usage

Create Schema

List Schemas

Validate Payload

Update Schema

Delete Schema

Using Schemas with Sources

Best Practices

Common Patterns

Allow Additional Properties

Optional with Default

String Formats

Pattern Validation