Core Concepts

Endpoints

An endpoint represents a URL where webhook payloads are delivered. Each endpoint has:

• URL — The target URL that receives webhook POST requests
• Events — Optional event filter (e.g., only deliver order.created events)
• Signing Secret — HMAC-SHA256 secret for payload verification (whsec_ prefix)
• docs.status — Active or inactive; inactive endpoints skip delivery

{
  "id": "ep_abc123",
  "url": "https://myapp.com/webhook",
  "description": "Order notifications",
  "signing_secret": "whsec_abc123xyz789...",
  "is_active": true,
  "event_filter": "order.*",
  "created_at": "2026-01-15T10:30:00Z"
}

Webhooks & Deliveries

A webhook is an event you send via the API. A delivery is the attempt to deliver that webhook to an endpoint.

• Event Types — String identifiers like order.created, user.updated
• Payloads — JSON data sent as the request body
• Delivery Status — pending, delivered, or failed
• Attempt Tracking — Each delivery attempt is recorded with status code, response body, and duration

Retries

Failed deliveries are automatically retried using exponential backoff with jitter. The default schedule:

After 6 failed attempts, the delivery is marked as failed and moved to the Dead Letter Queue. See Retries & DLQ for details.

Dead Letter Queue (DLQ)

When a delivery exhausts all retry attempts, it's preserved in the Dead Letter Queue. DLQ entries include:

• Original payload and event type
• All delivery attempts with error details
• Ability to replay — re-queue the delivery for another attempt
• Configurable retention (default: 30 days)

API Keys

API keys authenticate your requests. Keys use the hr_live_ prefix and are sent via Bearer auth:

Authorization: Bearer hr_live_abc123xyz789

• Keys are Argon2 hashed in the database — plaintext is never stored
• Multiple keys per account — rotate without downtime
• Scoped to your plan's rate limits