Skip to content

doc: document webhook delivery formats #127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bfabio merged 2 commits into from
Nov 11, 2026
Merged

doc: document webhook delivery formats #127

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2b7c93c
doc: document webhook delivery formats
bfabio Nov 9, 2026
13a15de
doc: clarify Standard Webhooks signing
bfabio Nov 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions open-catalog-api.oas.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,32 @@
4. Webhook subscribers receive a `POST` on every change to software
and publishers, so they do not need to poll.

## Webhook delivery formats

The webhook `format` determines the JSON body and authentication headers
sent to the webhook URL. Every delivery has `Content-Type: application/json`
and the `open-catalog-api-webhook/1.0` user agent.

- **default**: the body is `{"event":"create","subject":"/software/{id}"}`.
When a secret is configured, `X-Webhook-Signature` contains the lowercase
hexadecimal HMAC-SHA256 of the raw request body, using the secret as the key.
- **github**: the URL is a GitHub
[`repository_dispatch`](https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event)
endpoint. The body is `{"event_type":"software.create","client_payload":{"event":"create","subject":"/software/{id}"}}`.
Requests include `Accept: application/vnd.github+json` and
`X-GitHub-Api-Version: 2022-11-28`. When configured, the secret is a
GitHub token sent as `Authorization: Bearer {secret}`.
- **standard-webhooks**: the body is
`{"type":"software.create","timestamp":"2026-01-02T15:04:05Z","data":{"event":"create","subject":"/software/{id}"}}`.
It includes `webhook-id`, `webhook-timestamp` (Unix seconds) and, when a
secret is configured, `webhook-signature`. The secret is used as raw
UTF-8 bytes, not as a Base64 key with the `whsec_` prefix. The
signature is
`v1,{base64(HMAC-SHA256(secret, "{webhook-id}.{webhook-timestamp}.{body}"))}`.

The callback schemas below describe the default format. Consumers of the
other formats should use the delivery contract above.

## Resources

- **Software**: a piece of software and its `publiccode.yml`.
Expand Down Expand Up @@ -853,7 +879,7 @@
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
operationId: get-bundle

Check notice on line 882 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

no-method-name-in-operationId 

Avoid using method names in operationIds.
patch:
summary: Update a Bundle
description: Update a Bundle by its id
Expand Down Expand Up @@ -897,7 +923,7 @@
- bundles
security:
- bearerAuth: []
operationId: delete-bundle

Check notice on line 926 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

no-method-name-in-operationId 

Avoid using method names in operationIds.
responses:
'204':
$ref: '#/components/responses/NoContent'
Expand Down Expand Up @@ -979,7 +1005,7 @@
in: query
name: to
description: Only logs before this time (RFC 3339 datetime)
- schema:

Check notice on line 1008 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/paths/~1logs/get/parameters/5/schema
type: string
maxLength: 255
example: 'BAD publiccode'
Expand Down Expand Up @@ -1050,7 +1076,7 @@
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
operationId: get-log

Check notice on line 1079 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

no-method-name-in-operationId 

Avoid using method names in operationIds.
patch:
summary: Update a Log
description: Update a Log by its id
Expand Down Expand Up @@ -1092,7 +1118,7 @@
- logs
security:
- bearerAuth: []
operationId: delete-log

Check notice on line 1121 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

no-method-name-in-operationId 

Avoid using method names in operationIds.
responses:
'204':
$ref: '#/components/responses/NoContent'
Expand Down Expand Up @@ -1243,7 +1269,7 @@
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
operationId: get-event

Check notice on line 1272 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

no-method-name-in-operationId 

Avoid using method names in operationIds.
/catalogs:
get:
summary: List all Catalogs
Expand Down Expand Up @@ -2167,7 +2193,7 @@
type: object
additionalProperties: false
properties:
message:

Check notice on line 2196 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/paths/~1publishers~1%7BpublisherId%7D~1logs/post/requestBody/content/application~1json/schema/properties/message

Check warning on line 2196 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-maxlength 

Strings (non enum) must specify a maximum length. #/paths/~1publishers~1%7BpublisherId%7D~1logs/post/requestBody/content/application~1json/schema/properties/message "message.maxLength" property must be defined
type: string
minLength: 1
required:
Expand Down Expand Up @@ -2462,7 +2488,7 @@
ResourceCreate:
'{$request.body#/url}':
post:
description: The webhook called when a new resource is created
description: The webhook called in the default format when a new resource is created
requestBody:
required: true
content:
Expand Down Expand Up @@ -2490,7 +2516,7 @@
ResourceUpdate:
'{$request.body#/url}':
post:
description: The webhook called when a resource is updated
description: The webhook called in the default format when a resource is updated
requestBody:
required: true
content:
Expand Down Expand Up @@ -2518,7 +2544,7 @@
ResourceDelete:
'{$request.body#/url}':
post:
description: The webhook called when a resource is deleted
description: The webhook called in the default format when a resource is deleted
requestBody:
required: true
content:
Expand Down Expand Up @@ -2584,7 +2610,7 @@
schema:
$ref: '#/components/schemas/Error'
schemas:
AnalysisData:

Check warning on line 2613 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-constrained-additionalProperties 

Objects should not allow unconstrained additionalProperties. Disable them with `additionalProperties: false` or add `maxProperties`.
title: AnalysisData
type: object
nullable: true
Expand All @@ -2611,7 +2637,7 @@
readOnly: true
description: Timestamp of the last write (RFC 3339 datetime).
example: '2024-01-15T10:30:00Z'
additionalProperties: true

Check warning on line 2640 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-no-additionalProperties 

Objects should not allow unconstrained additionalProperties. Disable them with `additionalProperties: false` or add `maxProperties`.
example:
acme-security-scanner:
v: 1
Expand Down Expand Up @@ -2655,7 +2681,7 @@
- remove
- replace
- test
path:

Check notice on line 2684 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/JsonPatchRequest/items/properties/path
type: string
maxLength: 255
description: >
Expand All @@ -2666,7 +2692,7 @@
value:
description: The value to set. Required for add, replace, and test operations.
example: 'name: My Software'
from:

Check notice on line 2695 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/JsonPatchRequest/items/properties/from
type: string
maxLength: 255
description: Source JSON Pointer, used by move and copy operations.
Expand All @@ -2682,17 +2708,17 @@
pattern: >-
[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}
readOnly: true
name:

Check notice on line 2711 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/Bundle/properties/name
type: string

Check notice on line 2712 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in string.
minLength: 1

Check notice on line 2713 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in 1.
maxLength: 255

Check notice on line 2714 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in 255.
description:

Check notice on line 2715 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/Bundle/properties/description
type: string
maxLength: 1000
active:
type: boolean
default: true
softwareIds:

Check warning on line 2721 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-array-boundaries 

Schema of type array must specify maxItems and minItems. #/components/schemas/Bundle/properties/softwareIds "softwareIds.maxItems" property must be defined
type: array
minItems: 1
items:
Expand Down Expand Up @@ -2720,17 +2746,17 @@
type: object
additionalProperties: false
properties:
name:

Check notice on line 2749 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/BundlePost/properties/name
type: string

Check notice on line 2750 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in string.
minLength: 1

Check notice on line 2751 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in 1.
maxLength: 255

Check notice on line 2752 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in 255.
description:

Check notice on line 2753 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/BundlePost/properties/description
type: string
maxLength: 1000
active:
type: boolean
default: true
softwareIds:

Check warning on line 2759 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-array-boundaries 

Schema of type array must specify maxItems and minItems. #/components/schemas/BundlePost/properties/softwareIds "softwareIds.maxItems" property must be defined
type: array
minItems: 1
items:
Expand All @@ -2746,16 +2772,16 @@
type: object
additionalProperties: false
properties:
name:

Check notice on line 2775 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/BundlePatch/properties/name
type: string

Check notice on line 2776 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in string.
minLength: 1

Check notice on line 2777 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in 1.
maxLength: 255

Check notice on line 2778 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in 255.
description:

Check notice on line 2779 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/BundlePatch/properties/description
type: string
maxLength: 1000
active:
type: boolean
softwareIds:

Check warning on line 2784 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-array-boundaries 

Schema of type array must specify maxItems and minItems. #/components/schemas/BundlePatch/properties/softwareIds "softwareIds.maxItems" property must be defined
type: array
minItems: 1
items:
Expand Down Expand Up @@ -2866,13 +2892,13 @@
description: Unique identifier of the Catalog
example: 'a1b2c3d4-e5f6-4789-abcd-ef0123456789'
readOnly: true
name:

Check notice on line 2895 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/Catalog/properties/name
type: string

Check notice on line 2896 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in string.
minLength: 1

Check notice on line 2897 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in 1.
maxLength: 255

Check notice on line 2898 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in 255.
description: Human-readable name of the catalog

Check notice on line 2899 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in Human-readable name of the catalog.
example: 'Public Software Catalog'

Check notice on line 2900 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

use-recommended-names-in-schemas 

Use recommended variable names in Public Software Catalog.
alternativeId:

Check notice on line 2901 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/Catalog/properties/alternativeId
type: string
description: >
Optional alternative user-provided identifier for this Catalog.
Expand All @@ -2889,7 +2915,7 @@
description: Whether this Catalog is active or not
default: true
example: true
publishersNamespace:

Check notice on line 2918 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/Catalog/properties/publishersNamespace
type: string
maxLength: 255
description: >
Expand All @@ -2898,7 +2924,7 @@
each publiccode.yml organisation field equals
this prefix + the publisher alternativeId.
example: 'urn:x-italian-pa:'
scopes:

Check warning on line 2927 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-array-boundaries 

Schema of type array must specify maxItems and minItems. #/components/schemas/Catalog/properties/scopes "scopes.minItems" property must be defined
type: array
maxItems: 20
description: >
Expand All @@ -2911,7 +2937,7 @@
string up to 64 characters is accepted. An empty or
absent list means the catalog is thematic and not tied
to a specific place.
items:

Check notice on line 2940 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/Catalog/properties/scopes/items
type: string
minLength: 1
maxLength: 64
Expand All @@ -2919,7 +2945,7 @@
example:
- 'iso3166:IT'
- 'm49:150'
sources:

Check warning on line 2948 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-array-boundaries 

Schema of type array must specify maxItems and minItems. #/components/schemas/Catalog/properties/sources "sources.minItems" property must be defined
type: array
maxItems: 100
description: >
Expand Down Expand Up @@ -2954,7 +2980,7 @@
type: object
additionalProperties: false
properties:
driver:

Check notice on line 2983 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/CatalogSource/properties/driver
type: string
maxLength: 64
description: >
Expand All @@ -2974,7 +3000,7 @@
Optional arguments for the driver (e.g. a JSON
configuration file URL).
example: ['https://example.org/config.json']
items:

Check notice on line 3003 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/CatalogSource/properties/args/items
type: string
minLength: 1
maxLength: 2048
Expand Down Expand Up @@ -3354,7 +3380,7 @@
maxLength: 255
example: 'https://example.org/my-webhook-endpoint'
description: URL where the webhook payload will be delivered to
secret:

Check notice on line 3383 in open-catalog-api.oas.yaml

View workflow job for this annotation

GitHub Actions / Lint (pull_request)

sec-string-pattern-or-format-or-enum 

Strings (non enum) must specify a pattern or a format. #/components/schemas/Webhook/properties/secret
type: string
minLength: 16
maxLength: 256
Expand Down
Loading