Webhooks

Overview

Webhooks in our infrastructure are implemented as serverless functions with unique URLs that external services can call to trigger events in our system. They are routed through our central router to ensure WAF (Web Application Firewall) rules are applied to all incoming webhook requests.

Implementation Details

1. Unique Identifier Generation

Each webhook gets a random ID generated using RandomId, which ensures uniqueness and security:

const batchWebHookID = new random.RandomId("BatchWebHookID", {
  byteLength: 8,
});

2. Function Setup

Webhooks are implemented as AWS Lambda functions with necessary resources linked:

export const batchWebHook = new sst.aws.Function("BatchWebHook", {
  handler: "packages/functions/src/batch/index.handler",
  vpc,
  link: [
    secrets.BatchApiKey,
    db,
    batchPropertyCache,
    secrets.StripeSecret,
    coreDataCluster,
  ],
  // URL configuration below
});

3. URL Configuration with Router Integration

The webhook URL is configured through our router to ensure WAF rules are applied:

url: {
  router: {
    instance: router,
    domain: $interpolate`${domains.properties.webhooks.replace("{id}", batchWebHookID.b64Url)}`,
  },
}

4. Security Benefits

• WAF Protection: By routing through our router instance instead of exposing function URLs directly, WAF rules are applied to all incoming webhook requests
• Random IDs: Using random IDs in the URL path adds an additional layer of security
• VPC Integration: Webhooks run within our VPC for network isolation

5. Webhook URL Exposure

The webhook URL is exposed as an output that can be shared with external services:

export const outputs = {
  batchWebhookUrl: batchWebHook.url,
};

Current Webhook Implementations

• Batch Webhook: Handles callbacks from the Batch API for property data processing

Best Practices

1. Always route webhooks through the router to ensure WAF protection
2. Use random IDs in webhook URLs for additional security
3. Link only the necessary resources to webhook functions
4. Document the expected payload format for each webhook endpoint