GitHub webhook payload not matching schema

GitHub webhook payloads often “don’t match the schema” for one of a few common reasons:

1) GitHub payloads vary by event

Each webhook event has its own structure. For example:

• push
• pull_request
• issues
• release

If your schema expects one event type but GitHub sends another, validation will fail.

2) Fields may be optional or missing

GitHub payloads often omit fields depending on the event/state.
Example: sender, organization, repository, or nested objects can be present in some events and absent in others.

3) Type mismatch

Common mismatches:

• id sometimes treated as number but actually sent as string
• booleans vs strings
• nullable fields (null) not allowed by your schema

4) Extra fields

GitHub frequently includes additional properties. If your schema is strict (additionalProperties: false), validation can fail when GitHub adds new fields.

5) Arrays/object shapes differ

Nested objects may not always have the same keys. A schema that is too rigid for commit, actor, installation, etc. may reject valid payloads.

---

What to do

If using JSON Schema

Try making the schema more flexible:

• allow optional fields
• allow null where appropriate
• avoid strict additionalProperties: false unless necessary
• model event-specific schemas

If using code validation

Log the raw payload and compare it against the expected schema:

• inspect actual headers like X-GitHub-Event
• validate against the correct event schema
• check for strings vs numbers and missing fields

---

Example

If your schema expects:

{
  "id": 12345
}

But GitHub sends:

{
  "id": "12345"
}

Then you need:

{
  "id": {
    "type": "string"
  }
}

or a union type:

{
  "id": {
    "oneOf": [
      { "type": "string" },
      { "type": "integer" }
    ]
  }
}

---

Best next step

If you paste:

1. the webhook event type (X-GitHub-Event)
2. your schema
3. the actual payload or validation error

…I can point out the exact mismatch.