Add Webhooks

INFO

Webhook support is only available for Enterprise users only.

Why use the webhooks feature?

Built-in SDK support: Simplifies webhook adoption through built-in SDK support
Abstracted complexity: Consumers don’t need to worry about the cryptographic operations or dependencies
Secure by default: Consumers are forced to 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

Example

GitHub Example Source Code

You can see the full source code for this example here (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

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

const data = await sdk.validateWebhook({
  request: exampleFakeRequest,
  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 "../../models/errors/sdkvalidationerror.js";
import { WebhookAuthenticationError } from "../../types/webhooks.js";

const sdk = new Petstore();

try {
  await sdk.validateWebhook({
    request,
    secret: "<secret>",
  });
} catch (error) {
  if (error instanceof WebhookAuthenticationError) {
    console.error("Something wrong with the webhook signature? Or maybe the secret is wrong?", error);
  }
  if (error instanceof SDKValidationError) {
    console.error("Something wrong with the webhook request body? Maybe I'm on an outdated SDK version?", 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.

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`. Applicable to `type: signature`.

Signature Webhook Security

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.

Custom Webhook Security

x-speakeasy-webhooks:
  security:
    type: custom

This will generate a boilerplate file src/hooks/webhooks-custom-security.ts you can then modify the security logic in this file.

See this example source code in GitHub here (opens in a new tab).