openwebhooks_http

README

openwebhooks-http

openwebhooks-http is a secure, production-grade HTTP client used by OpenWebhooks to deliver outbound webhooks safely.

What is OpenWebhooks?

OpenWebhooks is an open-source infrastructure for delivering webhooks reliably and securely.

It’s designed for developers and teams who want full control over how events are delivered across systems — whether internal or external — without depending on external services. OpenWebhooks acts as the trusted layer between your system and any destination that needs to react to changes in real time.

Features

• Connection Pooling: Reuses HTTP connections to reduce latency and resource usage for repeated webhook deliveries.
• TLS Enforcement: Ensures all webhook requests use secure HTTPS connections with valid TLS certificates.
• SSRF Protection: Blocks requests to private IP ranges, localhost, and other unsafe network targets to prevent Server-Side Request Forgery.
• Safe Redirect Policies: Limits redirects, enforces scheme consistency, and revalidates redirect targets to prevent misuse.
• Request & Response Timeouts: Sets strict timeouts for requests and responses to prevent hanging connections.
• Slow Loris Protection: Detects and blocks endpoints that send response data too slowly to exhaust system resources.
• Response Size Limiting: Limits the maximum response size to avoid memory exhaustion or denial-of-service risks.
• Payload Signing: Signs webhook payloads using HMAC so receivers can verify integrity and authenticity.
• Replay Protection Support: Includes optional timestamp headers to help receivers detect and block replay attacks.

Install

go get github.com/openwebhooks/openwebhooks-http

import openwebhooks_http "github.com/openwebhooks/openwebhooks-http"

Usage

openWebhooksClient := openwebhooks_http.NewClient()

payload := []byte(`{"type":"user.created"}`)
secrets := []string{"whsec_abc123"}

response, err := openWebhooksClient.Post(ctx, "https://example.com/api/webhook", payload, secrets)

Contributing

Contributions are welcome!

If you have ideas for improvements, find a security issue, or want to add new features, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.

Documentation

Index

• func NewHttpClient(netDialerTimeout time.Duration, httpClientTimeout time.Duration) *http.Client
• type Client
  • func NewClient() *Client
  • func (c *Client) Post(ctx context.Context, target string, payload []byte, secrets []string) ([]byte, error)

Functions

func NewHttpClient

func NewHttpClient(netDialerTimeout time.Duration, httpClientTimeout time.Duration) *http.Client

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient() *Client

func (*Client) Post

func (c *Client) Post(ctx context.Context, target string, payload []byte, secrets []string) ([]byte, error)

Post sends a signed HTTP POST request with a JSON payload to a user-defined webhook endpoint.

This method performs the following steps:

• Validates the target URL and enforces HTTP/HTTPS schemes.
• Signs the payload using one or more shared secrets to generate HMAC signatures.
• Adds a timestamp and the generated signatures to the "X-Signature" header to ensure integrity and support replay protection.
• Sends the HTTP POST request with appropriate headers, including User-Agent and Content-Type.
• Limits the response body size to prevent resource exhaustion.
• Returns the response body if the request succeeds with a 2xx status code.

Parameters:

• ctx: The context for request cancellation and timeout control.
• target: The webhook endpoint URL.
• payload: The JSON payload to send.
• secrets: A list of shared secrets used for HMAC payload signing.

Returns:

• The response body as a byte slice if the request is successful.
• An error if URL validation fails, signing fails, the HTTP request fails, or a non-2xx response is received.