Product surfaces

Webhooks

Outbound + inbound. 5-state delivery machine. HMAC over bytes. Public receiver keys.

This page is the documentation contract for the Webhooks surface in Vadyl's final form. It is not a marketing summary: it names the authorities, projections, runtime behavior, examples, limits, errors, and observability expectations that every product implementation must honor.

What this surface owns

Webhooks owns the canonical product-facing contract described here; provider-specific machinery stays behind capability declarations.
Outbound + inbound. 5-state delivery machine. HMAC over bytes. Public receiver keys.
The final docs treat this as complete: REST, GraphQL, gRPC, SDK, CLI, MCP, dashboard, observability, limits, errors, and explainability are all covered as projections of one authority.

Canonical authorities

Authority	Role
`ExposureBindingDescriptor`	Defines how Webhooks appears through REST, OpenAPI, GraphQL, gRPC, SDK, CLI, MCP, dashboard, webhooks, realtime, and events.
`IApiOperationDispatcher`	Canonical owner for Webhooks; downstream surfaces derive from this rather than inventing their own truth.
`ContractProjectionDescriptor`	Projects Webhooks from canonical project state into every caller-visible contract.
`ProjectCapabilitySurfaceManifest`	Places Webhooks inside the UCSA taxonomy and enforces binding, grants, conformance, and consumption.

Projection coverage

Surface kinds	`WireSurface`, `OperationProjectionSurface`, `SdkSurface`, `CommandSurface`, `ToolSurface`, `UiProjectionSurface`
Projection facets	`Operations`, `Cli`, `ExposureBindings`
Protocols	`Rest`, `OpenApi`, `GraphQL`, `Grpc`, `Sdk`, `Cli`, `Mcp`, `Dashboard`
Public projections	REST; OpenAPI; GraphQL; gRPC; SDK; CLI; MCP; dashboard actions; webhooks; realtime

Project-scope parity

Publish, install, consume

Consumption evidence

Runtime behavior

thin controller dispatch
operation projection
descriptor hash validation
grant-set enforcement

REST and controller surface

Code-backed controllers are listed here so the docs menu does not hide the real endpoint surface. The complete route-by-route table remains in the REST controller atlas.

Controller	Base route	Endpoint count	Examples
Operation	`/api/Operation`	2	`POST Execute` `POST Plan`
ContractProjection	`/api/ContractProjection`	4	`GET descriptor` `GET {language}/declarations` `GET cli` `GET events`
Sdk	`/api/Sdk`	3	`POST generate` `GET languages` `GET versioning`
Webhook	`/api/webhooks and /api/Webhook`	14	`GET endpoints` `GET endpoints/{id}` `POST endpoints` `PUT endpoints/{id}`

SDK and CLI surface

Projection	Namespace / group	Coverage
SDK	`platform`	provider health/capabilities, runtime fabric scaling, distribution, version governance, data portability. Rendered methods: 12.
SDK	`mcp`	token issuance, exposure descriptors, tool invocation, resources, prompts. Rendered methods: 6.
SDK	`webhooks`	endpoint and receiver management, delivery replay, signature helpers, diagnostics. Rendered methods: 6.
SDK	`events`	emit, list, get, tail, replay, consumer offsets, ordered stream helpers. Rendered methods: 2.
CLI	`vadyl sdk`	Generate / inspect language SDKs. Rendered commands: 3.
CLI	`vadyl status`	Health and version. Rendered commands: 3.
CLI	`vadyl webhook`	Outbound endpoints, inbound receivers, deliveries, replay, secret rotation. Rendered commands: 10.
CLI	`vadyl events`	Tail / replay / search canonical event log. Rendered commands: 3.

Input request and output

webhooks.surface

POST /api/Operation/Execute HTTP/1.1
Host: api.vadyl.app
Authorization: Bearer $VADYL_TOKEN
X-Vadyl-Tenant: acme
X-Vadyl-Project: billing
Content-Type: application/json

{
  "surface": "webhooks",
  "publicationVersion": 412,
  "explain": true
}

Limits and quotas

Error model

Error	Meaning

Observability and explainability

Related references

Full surface atlas

Exposure bindings