Skip to content

Add OpenTelemetry hooks for observability #13

Description

@JosephDoUrden

Summary

Add optional OpenTelemetry instrumentation to provide observability into webhook signing and verification operations.

Context

From PRD.md Future Enhancements: "OpenTelemetry hooks"

Production systems need visibility into webhook verification performance, failure rates, and error types.

Scope

  • Add optional OTel spans for signWebhook and verifyWebhook operations
  • Record attributes: version, timestamp age, verification result, error type
  • Add metrics: verification success/failure counters, latency histograms
  • Keep OTel as an optional peer dependency (not required)

Implementation Notes

  • Use @opentelemetry/api as an optional peer dependency
  • Gracefully degrade when OTel is not installed (no-op)
  • Consider a separate export path (e.g. webhook-hmac-kit/otel)
  • Follow OTel semantic conventions for HTTP/messaging

Acceptance Criteria

  • Spans are created for sign and verify operations
  • Error attributes are recorded on verification failures
  • Works without OTel installed (no runtime errors)
  • Documentation with setup examples

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions