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 webhooks
import (
    "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.