Add Webhooks
INFO
Since version 3.1, OpenAPI supports webhooks, which are incoming HTTP requests in response to events.
The new webhooks feature is described similarly to the existing callback functionality. The new webhooks
keyword is a top-level element alongside paths
. Version 3.1 also brings changes to the required fields: OpenAPI 3.0 requires openapi
, info
, and paths, while OpenAPI 3.1 requires openapi
, info
, and at least one of paths
, webhooks
, or components
. This allows valid API descriptions to contain only outgoing API calls, incoming webhooks, or components that might be referred to by other documents, or any combination of these.
To generate types for webhooks, Speakeasy natively supports the webhook
keyword during SDK creation. For each defined webhook
in your OpenAPI spec, Speakeasy will generate the types for your webhook request and response objects. This ensures that whatever the endpoint type, your users have a consistent experience interacting with your API, and you can publish a single package for your users to consume.
Here is an example of a webhook request posted from a system when a new pet is registered at the Petshop.
OpenAPI
webhooks: newPet: post: operationId: newPetEvent requestBody: description: Information about a new pet in the system content: application/json: schema: $ref: "#/components/schemas/Pet" responses: "200": description: Return a 200 status
Here is an example of the generated types for Golang, but the same applies to all other supported languages.
SDK Output
package webhooksimport ( "openapi/pkg/models/shared")type NewPetRequest struct { Request *shared.Pet `request:"mediaType=application/json"`}type NewPetResponse struct { ContentType string StatusCode int64}
In the webhooks section, each incoming webhook request has an operationId
(such as newPetEvent
in the example above). You don’t need to specify the URL path that the webhook will come in on (often the user can nominate that anyway), only explain what will arrive, and your users will get a type to manage it in code.
INFO
As of version 3.1, PathItem
is allowed in the components
section, and you can use $ref
to reference a pathItem
from a path, callback, or webhook.
Speakeasy will support native serialization and deserialization methods for webhook types in the future.