Add Webhooks to your SDKs

Why use the webhooks feature?

Built-in SDK support: It simplifies webhook adoption through built-in SDK support.
Abstracted complexity: Consumers don’t need to worry about cryptographic operations or dependencies.
Default security: Consumers have to verify the signature in order to unpack the webhook data.
Type-safe consumption: Consumers get schema-validated data and types.
Type-safe sending: Producers can send schema-validated data through type-safe SDK methods.

Getting started

INFO

Webhooks are a paid add on, reach out to us to discuss pricing (opens in a new tab).

You must have a Speakeasy Business or Enterprise plan.
Run the following command to activate webhooks in your SDK generation configuration:

speakeasy billing activate -f webhooks

Example

GitHub example source code

You can see the full source code for this example in the webhooks example repo (opens in a new tab).

OpenAPI

openapi: 3.1.0 # You must use OpenAPI 3.1.0 or higher
info:
  title: Petstore API
  version: 1.0.0
servers:
  - url: https://petstore.swagger.io/v2
paths:
  /pets:
    post:
      operationId: addPet
      requestBody:
        required: true
        content:
          application/json: 
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: Okay
x-speakeasy-webhooks:
  security:
    type: signature
    headerName: x-signature
    signatureTextEncoding: base64
    algorithm: hmac-sha256
webhooks:
  pet.created:
    post:
      operationId: sendPetCreated
      requestBody:
        required: true
        content:
          application/json: 
            schema:
              $ref: '#/components/schemas/PetCreated'
      responses:
        '200':
          description: Okay
  pet.deleted:
    post:
      operationId: sendPetDeleted
      requestBody:
        required: true
        content:
          application/json: 
            schema:
              $ref: '#/components/schemas/PetDeleted'
      responses:
        '200':
          description: Okay
components:
  schemas:
    PetCreated:
      type: object
      properties:
        type:
          type: string
          enum:
            - pet.created # This is the payload discriminator
        pet:
          $ref: '#/components/schemas/Pet'
      required:
        - type
        - pet
    PetDeleted:
      type: object
      properties:
        type:
          type: string
          enum:
            - pet.deleted # This is the payload discriminator
        id:
          type: string
      required:
        - type
        - id
    Pet:
      type: object
      properties:
        id:
          type: string
      required:
        - id

For webhook consumers

The validateWebhook() function is currently only implemented in the TypeScript SDK, with support for additional languages planned for future releases. While other languages will generate webhook types, this discriminator method is TypeScript-only.

import { Petstore } from "petstore";
const sdk = new Petstore();

const data = await sdk.validateWebhook({
  request,
  secret: "<secret>",
});

console.log(data);

if (data.type === "pet.created") {
  console.log("Pet created", data.pet);
}

if (data.type === "pet.deleted") {
  console.log("Pet deleted", data.id);
}

Error handling

import { Petstore } from "petstore";
import { SDKValidationError } from "petstore/models/errors/sdkvalidationerror.js";
import { WebhookAuthenticationError } from "petstore/types/webhooks.js";

const sdk = new Petstore();

try {
  await sdk.validateWebhook({
    request,
    secret: "<secret>",
  });
} catch (error) {
  if (error instanceof WebhookAuthenticationError) {
      // Thrown when signature verification fails, usually due to:
      // - Incorrect webhook secret
      // - Modified request payload
      // - Wrong signature format
      console.error("Webhook authentication failed", error);
  }
  if (error instanceof SDKValidationError) {
    // Thrown when the webhook request body is unrecognised, usually due 
    // to an outdated SDK version or un-docummented payloads
    console.error("Webhook request body is invalid", error);
  }
  throw error;
}

For webhook producers

import { Petstore } from "petstore";

const sdk = new Petstore();

const data = await sdk.sendPetCreated(
  {
    url: "https://example.com/my-webhook-handler",
    secret: "<secret>",
  },
  {
    type: "pet.created",
    pet: { id: "dog" },
  }
);

`x-speakeasy-webhooks`

The x-speakeasy-webhooks extension is used to define the webhooks for your API.

Property	Type	Description
`security`	`WebhookSecurity`	The security configuration for the webhooks.

`x-speakeasy-webhooks.security`

Property	Type	Description
`type`	`string`	The type of security to use for the webhooks. Valid values are `signature` and `custom`.
`headerName`	`string`	The name of the header to use for the security token / signature.
`signatureTextEncoding`	`string`	The text encoding of the signature. Applicable to `type: signature`.
`algorithm`	`string`	The algorithm to use for the signature. Valid values are: `hmac-sha256`.

`x-speakeasy-webhooks.security.type: signature`

x-speakeasy-webhooks:
  security:
    type: signature
    headerName: x-signature
    signatureTextEncoding: base64
    algorithm: hmac-sha256

This will apply HMAC SHA256 to the body of the webhook request and put it in a header.

`x-speakeasy-webhooks.security.type: custom`

x-speakeasy-webhooks:
  security:
    type: custom

This generates the src/hooks/webhooks-custom-security.ts boilerplate file, which you can then use to modify the security logic.

See the source code for this example in the GitHub repo (opens in a new tab).