Skip to content

Webhook Handler

Purpose

The webhook handler is a Lambda function that receives GitHub webhook events via API Gateway. It validates incoming webhooks, determines if they're relevant to documentation (changes to /docs folders), and triggers the rebuilder Lambda when necessary.

How It Works

The webhook handler processes GitHub events in three stages:

  1. Validation - Verifies webhook signatures using HMAC SHA-256 to ensure requests are authentic from GitHub
  2. Event Filtering - Inspects push events to determine if /docs folders were modified on the default branch
  3. Trigger - Invokes the docs-rebuilder Lambda asynchronously when relevant changes are detected

Event Types Handled

  • ping - GitHub's test event when configuring webhooks
  • installation.created - When the GitHub App is installed in a new organization (triggers full rebuild)
  • push - Code pushes; only triggers rebuild if /docs files changed on the default branch

Structure

Single-file Lambda (index.ts) with focused responsibilities:

  • handler() - Main Lambda entry point, processes API Gateway events
  • verifySignature() - HMAC validation using webhook secret from AWS Secrets Manager
  • triggerRebuilder() - Invokes the docs-rebuilder Lambda asynchronously
  • getWebhookSecret() - Retrieves and caches GitHub webhook secret

Monitoring

Logs are available in DataDog: https://app.datadoghq.eu/logs?query=service%3Adocs-builder

The function is instrumented with DataDog APM for structured logging and tracing.

Last updated: March 31, 2026 at 11:02
By: Axel Tetzlaff