Docs
Overview Ingress endpoints Verification Delivery model Retries & backoff Replay Observability Dead-letter Rate-limit shielding Security notes

Documentation

Hooklayer improves webhook reliability by separating “receive and persist” from “deliver to your systems”. This page focuses on concepts and recommended operating patterns.

Overview

Hooklayer receives inbound webhooks at dedicated ingress endpoints. It verifies authenticity (signatures and/or IP allowlists), stores events durably, then delivers them to one or more destinations you control. Each delivery attempt is recorded with status codes, timing, and response body snippets for debugging.

Receive & verify
Reject spoofed traffic; accept valid events and acknowledge quickly.
Store first
Persist the full payload and metadata to an event log before delivery.
Deliver
Forward to destinations with strict timeouts and well-defined retry policy.
Observe
Inbox + logs let you debug quickly and replay events safely.

Ingress endpoints

An ingress endpoint is the public URL you give to webhook senders. Hooklayer responds fast after verification and storage, decoupling sender latency from your downstream systems.

POST https://api.hooklayer.com/ingest/your-endpoint-key Headers: Hooklayer-Signature: v1=... Body: (raw JSON or any content-type)

Keep the inbound payload exactly as received. Hooklayer’s goal is reliability and traceability, not payload transformation.

Verification

Verification can include signature checks (recommended) and optional IP allowlisting. If verification fails, Hooklayer returns an error and the event is not stored.

Signatures
Validate a shared secret using an HMAC-style signature over the raw request body and selected headers.
IP allowlists
Optional additional filter for known sender egress ranges. Use carefully if ranges are dynamic.
Recommendation
Prefer signatures for authenticity. IP allowlists are useful as a second factor but can break if sender ranges change.

Delivery model

Hooklayer forwards each stored event to one or more destinations you configure. Delivery attempts are isolated and tracked individually. Destinations should respond quickly (ideally < 2 seconds). If your processing is slow, enqueue internally and respond 2xx.

Best practice for your destination
  • Validate idempotency using an event id header.
  • Do minimal work inline; enqueue heavy processing.
  • Return 2xx only after safely persisting/queuing.

Retries & backoff

Retries trigger on network errors, timeouts, and non-2xx responses according to policy. Backoff spreads attempts to avoid amplifying outages and prevents retry storms.

Exponential backoff
Increasing delay between attempts reduces pressure on downstream systems.
Retry policy
Configure max attempts, timeouts, and retryable status codes per destination.

Replay

Replay lets you re-deliver events after fixes, migrations, or temporary outages. Replays are explicit actions, not automatic retries. You can replay an individual event or a filtered set (by time range or type).

Replay safety
Ensure destinations are idempotent. Use event ids to deduplicate on your side.

Observability

The inbox provides searchable event history and delivery attempts. Key metrics include success rate, latency, retry counts, and the size of the dead-letter queue.

What you should monitor
  • Delivery success rate per destination
  • Spike detection on ingress volume
  • Increase in retries / timeouts
  • Dead-letter growth

Dead-letter

Events that exceed the maximum retry attempts are placed into a dead-letter state. They remain available for inspection and can be replayed once the issue is resolved.

Rate-limit shielding

Hooklayer can smooth bursts and apply per-destination throughput limits to prevent your systems from being overwhelmed. This reduces 429 responses and protects internal queues.

Typical configuration
Set a max concurrency and a max requests/second per destination. Combine with retries and jittered backoff.

Security notes

  • Always verify signatures using the raw body (avoid JSON re-serialization).
  • Use TLS everywhere and rotate signing secrets periodically.
  • Log redaction: avoid storing secrets in webhook payloads where possible.
  • Apply least privilege to destinations and restrict outbound access where feasible.