[RFC] Webhooks

[fredericbarthelet]

The goal of this discussion is to get feedback on the "Webhooks" component.

If you are new to Lift, a quick intro: it's a Serverless plugin that can be installed via npm and enabled in any serverless.yml file.

Here is what we are planning so far.

Use case

Receive event notifications with HTTP webhooks

Every application needs to interact with an ecosystem of 3rd party SaaS providers.
Implementing a webhook HTTP endpoint in your application allows this ecosystem of external applications to notify you. Your application can then react to those notifications and perform tasks accordingly.

Quick start

webhooks:
  stripe:
    authorizer: # required, defines your custom authorizer logic. Contains all properties of functions except events 
      handler: myAuthorizer.main
    path: /my-webhook-endpoint # required : path the endpoint should be exposed at
    type: $request.body.type # optional : any static string or dynamically resolvable by API Gateway. Used to hydrate Eventbridge event's DetailType property

How it works

The webhook component deploys the following resources:

• an API Gateway V2 HTTP API and its $default stage (reused for all webhooks defined in the service file)
• an Eventbridge EventBus (reused for all webhooks defined in the service file)
• an IAM Role allowing API Gateway to use PutEvents API of Eventbridge (reused for all webhooks defined in the service file)
• an API Gateway V2 route
• an API Gateway V2 integration defining mappings of parameters between the HTTP request body and the Eventbridge Event's body
• a custom Lambda authorizer to handle signature verification at API Gateway level

Lambda (or any other service) consumers

In its current form, the component scope ends at publishing events in the event bus. Eventbridge rules and Lambda targets are not part of this component, and can be natively defined using Serverless framework eventBridge event type.

Another way to look at it is to provide the full experience and allow user definition of consumer directly within the component.

webhooks:
 stripe:
   authorizer:
     handler: myAuthorizer.main
   path: /my-webhook-endpoint
   type: $request.body.type
   consumers:
     sendThankYouEmail:
       handler: sendEmail.main
       type:
         - invoice.paid
     sendReminder:
       handler: sendReminder.main
       type:
         - charge.overdue

Such implementation removes the need to reference the component (as shown below). It also allows the setup of an additional security layer of DLQ on each consumer (to ensure no message are lost) and a retry policy (that the user may not implement if he defines himself the consumers with all options of the Serverless Framework).

WDYT ?

References

The component will introduce ${webhooks:xxx} variables to easily reference queues in serverless.yml, without using CloudFormation.

For example:

functions:
  sendThankYouEmail:
    handler: sendEmail.main
    events:
      - eventBridge:
          eventBus: ${webhook:busName}
          pattern:
            source:
              - stripe
            detail-type:
              - invoice.paid

Configuration reference

Path (required)

webhooks:
  stripe:
    path: /my-path

The endpoint your webhook should be exposed on. Always starts with a /.
The final URL for the webhook endpoint will be displayed in the information section when running a serverless deploy command and will be POST https://{id}.execute-api.{region}.amazonaws.com{path}

Authorizer (required)

webhooks:
  stripe:
    authorizer:
      handler: stripe/authorizer.main

The Lambda "stripe-authorizer" function is configured inside the webhook, instead of being defined in the functions section.

The only required value is the handler: this should point to the code that authenticate 3rd party notification. The handler will receive an event from API Gateway using payload format v2. The handler should be written to return a boolean.

All settings allowed for functions can be used under the authorizer key. For example:

webhooks:
  stripe:
    authorizer:
      handler: stripe/authorizer.main
      environment:
        STRIPE_SECRET: my-secret

Lift will automatically configure the function to be triggered by API Gateway. It is not necessary to define events on the function.

Type (optional)

Defaults toWebhook.

Can either be a dynamic path selector:

webhooks:
  stripe:
    type: $request.body.type

Or a static string:

webhooks:
  stripe:
    type: stripe

Always favor dynamic path selector to ensure the minimum amount of compute is executed downstream. The list of available dynamic selector is available in API Gateway documentation.

Additional functionalities

Alarm

Alarm can be implemented for 2 situations:

• unexpected rate of 4xx errors on the HTTP endpoint (bad signature check of Denial of Wallet attempt)
• undelivered Eventbridge events to targets (require consumers to be part of the component)

[qhello]

@fredericbarthelet I really like the implementation choice you've made for lift's webhook construct. And I wish I could use it in my usecase.

This construct won't work with Stripe webhook though, therefore the example config you've written are kinda misleading:

• Stripe uses $request.header.stripe-signature as the Authorizer's identity source, compared to the hardcoded $request.header.Authorization
• Lambda authorizer will not be able to generate & verify webhook stripe-signature, as API Gateway doesn’t pass body property to custom authorizers.

[renanwilliam]

Fully agree with this comment; it's not possible to validate using an authorizer (considering the Stripe use case)