Payload Validation

Define a schema for each hook to validate incoming JSON payloads before execution.

Defining fields

[hooks.payload]
[[hooks.payload.fields]]
name = "repo"
type = "string"
required = true

[[hooks.payload.fields]]
name = "branch"
type = "string"
required = false

[[hooks.payload.fields]]
name = "force"
type = "boolean"
required = false

Supported types

Type	Description
`string`	Text values
`number`	Integer or floating-point numbers
`boolean`	`true` or `false`
`object`	Nested JSON objects
`array`	JSON arrays

Validation behavior

Missing Content-Type: application/json header: body is treated as {}
Malformed JSON: returns 400 Bad Request
Schema violation: returns 422 Unprocessable Entity with details
Empty body: treated as {} (only fails if required fields are defined)
Extra fields not in the schema are silently accepted

Example error response

{
  "error": "payload validation failed",
  "details": [
    "missing required field: repo",
    "field 'force' expected boolean, got string"
  ]
}