Core Concepts
Understand the fundamental building blocks of HookSniff.
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.createdevents) - 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, orfailed - 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:
| Attempt | Delay | Cumulative |
|---|---|---|
| 1 | Immediate | 0 |
| 2 | 10 seconds | 10s |
| 3 | 30 seconds | 40s |
| 4 | 2 minutes | ~2.5m |
| 5 | 10 minutes | ~12.5m |
| 6 | 30 minutes | ~42.5m |
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
FIFO Delivery
HookSniff delivers webhooks in FIFO order (first-in, first-out) per endpoint. Each delivery includes a sequence number:
{
"delivery_id": "wh_xyz789",
"sequence_number": 42,
"event": "order.created",
"data": { "order_id": "12345" },
"timestamp": "2026-01-15T10:30:00Z"
}Use sequence numbers to detect gaps or reorder events on your end.