Product Updates

Speakeasy SDK generation now supports webhooks

David Adler

December 3, 2024

We’re excited to announce that Speakeasy SDK generation now supports webhooks. This new feature makes it dramatically easier for both API producers and consumers to work with webhooks by providing type-safe handlers and built-in security verification, all powered by OpenAPI-native features.

The webhook integration challenge

If you maintain an API platform, you almost certainly have webhooks. But implementing webhook support has always been more complex than it needs to be, with challenges on both sides of the integration:

For API consumers, integrating webhooks typically involves:

• Implementing complex security verification from scratch
• Manual type construction and validation
• Handling undefined or unexpected payloads
• Managing authentication secrets
• Building resilient processing infrastructure

For API producers:

• Writing extensive documentation for webhook security
• Maintaining separate authentication systems
• Ensuring correct payload construction
• Managing webhook delivery and retries
• Supporting customers through integration challenges

The result? Developers spend more time wrestling to integrate with the webhook system than building product on top of it.

Better webhooks for producers & consumers

Our new webhook support simplifies this entire process by generating typed webhook handlers with built-in security verification. Here’s what that looks like in practice.

Consumer Support

const res = await sdk.validateWebhook({ request, secret });

if (res.error) {
  throw res.error; // Failed auth or unknown payload
}

const data = res.data;

if (data.type === 'company.created') {
  return myHandleCompanyCreated(data);
}

if (data.type === 'company.deleted') {
  return myHandleCompanyDeleted(data);
}

if (data.type === 'connection.created') {
  return myHandleConnection(data);
}

throw new Error(`Unhandled webhook payload: ${res.inferredType}`);

No more implementing HMAC SHA-256 verification from scratch. No more debugging undefined properties in production. Just install the SDK and start processing webhooks with confidence.

Producer Support

Generate convenience methods for producers to correctly construct and sign webhook payloads.

const finotech = new Finotech();

const result = await finotech.webhooks.sendCompanyCreated({
	recipient: {
	  url: "https://bank.com/finotech-webhooks",
	  secret: "secret-key"
	},
	{ id: "foo", name: "Foo Inc" }
});

Key Features

Type-Safe: All webhook payloads are fully typed, letting you catch integration issues at compile time rather than production.

Built-in Security: Support for industry-standard webhook security including HMAC SHA-256 signing, with more verification methods coming soon.

OpenAPI Native: Webhooks are defined right in your OpenAPI spec, ensuring your SDK, docs, and webhook interfaces stay in sync as your API evolves.

Getting Started

The magic happens through OpenAPI’s native webhook support. Simply add add our custom extension to configure your webhook security and your SDK will generate the rest:

openapi: 3.1.1
paths:
  ...
x-speakeasy-webhooks:
  security:
    type: signature # a preset which signs the request body with HMAC
    name: x-signature # the name of the header
    encoding: base64 # encoding of the signature in the header
    algorithm: hmac-sha256
webhooks:
  user.created:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
              required:
                - id
      responses:
        '200':
          description: Okay

The SDK will sign the request body. More complex signing schemes are also supported. Get in touch to find out how to support your signing scheme.

Webhooks maturity

Webhook support is available today in TypeScript, with support for additional languages rolling out soon. We’ve also got some exciting features on our roadmap:

• Asymmetric signature verification
• Key rotation support
• Custom signing scheme support
• Infrastructure for reliable webhook delivery and processing

For existing Speakeasy Enterprise customers, define webhooks in your OpenAPI spec and we’ll automatically include webhook generation in your next action run. For new customers, you can start generating webhook-enabled SDKs today by signing up (opens in a new tab).

Join the growing number of companies using Speakeasy to deliver exceptional API experiences, now with first-class webhook support!