Add webhooks to 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 must verify the signature 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.

1. You must have a Speakeasy Business or Enterprise plan.
2. Enable the webhooks add-on to your account under settings/billing:

app.speakeasy.com

Example

GitHub example source code

You can see the full source code for this example in the webhooks example repo.

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

security

Type

WebhookSecurity

Description

The security configuration for the webhooks.

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

x-speakeasy-webhooks.security

Property

type

Type

string

Description

The type of security to use for the webhooks. Valid values are signature and custom.

headerName

Type

string

Description

The name of the header to use for the security token / signature.

signatureTextEncoding

Type

string

Description

The text encoding of the signature. Applicable to type: signature.

algorithm

Type

string

Description

The algorithm to use for the signature. Valid values are: hmac-sha256.

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.