Speakeasy Logo
Skip to Content
DocumentationCustomizeAdd webhooks to your SDKs

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 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
Webhooks add on in the Speakeasy dashboard.

Example

GitHub example source code

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

OpenAPI

# !focus(1,20:50,59,71)
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
The security configuration for the webhooks.

x-speakeasy-webhooks.security

Property
Type
Description
The type of security to use for the webhooks. Valid values are
and
.
Type
Description
The name of the header to use for the security token / signature.
Type
Description
The text encoding of the signature. Applicable to
.
Type
Description
The algorithm to use for the signature. Valid values are:
.

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 .

Last updated on