---
title: "HitKeep 2.11.0: Signed Webhooks, Bounded Retries, And Delivery History | HitKeep"
description: "HitKeep 2.11.0 adds HMAC-signed outbound webhooks for site and instance events, with test delivery, bounded retries, secret rotation, and paginated delivery history."
canonical: "https://hitkeep.com/blog/hitkeep-2-11-0/"
---

[← All posts](https://hitkeep.com/blog/)

# HitKeep 2.11.0: Signed Webhooks, Bounded Retries, And Delivery History

Published July 11, 2026·[Pascale Beier, HitKeep maintainer](https://github.com/pascalebeier)·6 min read

![HitKeep 2.11.0 release artwork showing an operational event passing through an HMAC-SHA256 signed HTTPS request into successful delivery history](https://hitkeep.com/_astro/hitkeep-2-11-0-hero.7IlyQT_L_ZoXha2.webp)

Operational changes are useful outside an analytics dashboard. A goal conversion may need to notify billing, a completed import may unblock a migration, and a team membership change may need to update an internal system. Polling the REST API adds delay and repeated work.

HitKeep 2.11.0 adds signed outbound webhooks for those workflows. Site and instance administrators can subscribe an HTTPS endpoint to the events they need, send a test delivery, rotate its signing secret, and inspect delivery attempts without adding a separate integration service to HitKeep.

## What Shipped

- **Site and instance webhooks:** subscribe one endpoint to a site’s events or use instance scope for cross-site and administrative events.
- **HMAC-SHA256 signatures:** every request signs its timestamp and exact JSON body with a secret shown only after creation or rotation.
- **Bounded retries:** unsuccessful deliveries use exponential backoff, with six attempts by default and a six-hour maximum delay.
- **Test delivery:** queue a `webhook.test` event before connecting a production workflow.
- **Delivery history:** inspect event type, status, attempts, response code, and creation time in a paginated, sortable table.
- **Focused administration:** search and sort configured endpoints, scan subscribed events, and open delivery, test, edit, rotate, or delete actions from the row menu.
- **Destination protection:** production endpoints require HTTPS and cannot resolve to loopback, private, link-local, multicast, documentation, or other reserved addresses.
- **Single-binary operation:** the dispatcher, retry worker, recovery sweep, and retention cleanup run inside the existing HitKeep process.

![HitKeep 2.11 webhook administration table showing a searchable HTTPS endpoint, subscribed operational events, enabled status, sortable columns, pagination, and row actions](https://hitkeep.com/_astro/integration-webhooks.X_9n_d0y_Z1i06jg.webp)

Configured endpoints reuse HitKeep’s searchable table and row-action patterns; the event-count popover keeps larger subscriptions scannable.

## Verify The Exact Request Body

Each delivery includes a Unix timestamp and a `v1` HMAC-SHA256 signature. Verify the original bytes before decoding JSON; parsing and re-serializing the body can change whitespace or key ordering and invalidate the signature.

```
body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
if err != nil {
  http.Error(w, "invalid body", http.StatusBadRequest)
  return
}

timestamp := r.Header.Get("X-HitKeep-Timestamp")
signature := strings.TrimPrefix(
  r.Header.Get("X-HitKeep-Signature"),
  "v1=",
)
provided, err := hex.DecodeString(signature)
if err != nil {
  http.Error(w, "invalid signature", http.StatusUnauthorized)
  return
}

mac := hmac.New(sha256.New, []byte(signingSecret))
mac.Write([]byte(timestamp + "."))
mac.Write(body)
if !hmac.Equal(mac.Sum(nil), provided) {
  http.Error(w, "invalid signature", http.StatusUnauthorized)
  return
}
```

Receivers should also reject stale timestamps and persist `X-HitKeep-Event-ID` or `X-HitKeep-Delivery-ID` before returning success. Delivery is at least once, and events may arrive out of order, so downstream processing must be idempotent.

The [signed webhook guide](https://hitkeep.com/guides/integrations/webhooks/) includes a complete Go receiver with timestamp validation and the full request-header contract.

## Events At The Right Scope

Site webhooks cover lifecycle, goal, import, and test events for one site:

- `site.updated` and `site.deleted`
- `goal.created`, `goal.updated`, `goal.deleted`, and `goal.converted`
- `import.completed` and `import.failed`
- `webhook.test`

Instance webhooks can subscribe to every site event plus `site.created`, user lifecycle events, team lifecycle events, and team membership changes. The dashboard loads the valid event catalog for the selected scope, and the API rejects invalid combinations.

This is deliberately an operational event surface, not a raw analytics stream. Webhook payloads do not export pageview histories, visitor records, form contents, or Ask AI conversations. Use [open exports and takeout](https://hitkeep.com/guides/data/takeout/) when another system needs analytics data rather than a notification that an operational change happened.

## One-Time Secrets And Rotation

Creating a webhook returns its signing secret once. The dashboard presents it through the same one-time credential pattern used for API client tokens: copy it into the receiver’s secret store before leaving the page.

Rotation replaces the configured secret and re-signs pending, retrying, and processing delivery records with the new value. A request already in flight may still carry the previous signature, so receivers that rotate during active delivery should allow a short overlap window.

Webhook administration remains a human dashboard workflow. Instance owners and administrators can manage instance webhooks. Site owners and administrators can manage a site’s webhooks. Editors, viewers, instance users, and delegated API clients cannot create endpoints or rotate secrets. The [roles and permissions guide](https://hitkeep.com/guides/admin/permissions/) documents the complete boundary.

## Retries Without An Unbounded Queue

Any `2xx` response marks a delivery successful. Timeouts, connection failures, and non-`2xx` responses retry with exponential backoff. The defaults keep failure bounded:

| Behavior | Default |
| --- | --- |
| Request timeout | 10 seconds |
| Maximum attempts | 6 total attempts |
| Initial retry delay | 30 seconds |
| Maximum retry delay | 6 hours |
| Global delivery concurrency | 8 |
| Per-endpoint concurrency | 1 |
| Delivery-history retention | 30 days |
| Recovery sweep | Every 30 seconds |

Operators can tune these limits through the [outbound webhook configuration](https://hitkeep.com/reference/configuration/#outbound-webhook-delivery). The default per-endpoint concurrency of one prevents one slow receiver from being flooded, while the global limit keeps outbound work predictable inside the single process.

Delivery history stores outcomes and attempt metadata, not saved response bodies or secrets. The dashboard exposes that history in a paginated and sortable table, so a failed endpoint can be diagnosed without turning the UI into a raw payload archive.

![HitKeep 2.11 delivery history showing a successful signed webhook.test request with one attempt and an HTTP 204 response](https://hitkeep.com/_astro/integration-webhook-deliveries.OU4qcerD_Zw9P0R.webp)

A successful test delivery records the event, terminal status, attempt count, response code, and creation time without retaining the response body or signing secret.

## Safer Outbound Destinations

An outbound webhook feature creates a server-side request boundary, so endpoint validation happens both when an administrator saves the URL and immediately before delivery. Production destinations must use HTTPS. HitKeep does not follow redirects, does not inherit proxy settings for webhook delivery, and blocks hostnames that resolve to non-public address space.

Self-hosted developers can explicitly enable HTTP and private targets with `HITKEEP_WEBHOOK_ALLOW_DEVELOPMENT_TARGETS=true`. That flag removes the destination protections intended to prevent server-side request forgery and should never be enabled in production. The [security reference](https://hitkeep.com/reference/security/) covers webhook delivery alongside HitKeep’s other optional outbound connections.

## What Is Not Changing

HitKeep 2.11.0 keeps the same operating model:

- one Go binary
- embedded DuckDB data stores
- embedded NSQ queueing
- no required PostgreSQL, Redis, Kafka, ClickHouse, or separate integration service
- cookie-free browser tracking by default
- open export paths
- self-hosted and managed cloud built from the same product foundation

Webhooks add outbound operational delivery; they do not change browser tracking or broaden the stored analytics data model.

## Upgrade Guidance

Upgrade to 2.11.0 when another system needs to react to HitKeep goal, import, site, team, or user changes without polling.

After upgrading:

1. Open **Integration → Webhooks** and choose site or instance scope.
2. Create an HTTPS endpoint and subscribe only to the events the receiver needs.
3. Store the one-time signing secret outside HitKeep.
4. Send a test event and verify the timestamp, signature, and delivery ID.
5. Confirm the delivery appears as successful in delivery history.
6. Review retry, concurrency, and retention defaults before enabling a high-volume workflow.

## Read More

- [Configure and verify signed outbound webhooks](https://hitkeep.com/guides/integrations/webhooks/)
- [Webhook roles and permissions](https://hitkeep.com/guides/admin/permissions/)
- [Outbound webhook configuration](https://hitkeep.com/reference/configuration/#outbound-webhook-delivery)
- [HitKeep security model](https://hitkeep.com/reference/security/)
- [Runtime facts and product limits](https://hitkeep.com/reference/facts-and-limits/)
- [Public roadmap](https://hitkeep.com/support/roadmap/)

Self-hosted HitKeep includes webhook delivery in the same binary as the dashboard, queue, and database. If you want signed operational delivery without managing upgrades, backups, and worker operations, [start a managed HitKeep Cloud deployment](https://cloud.hitkeep.eu/signup?plan=free&billing=monthly&utm_source=hitkeep_docs&utm_medium=referral&utm_campaign=cloud_signup&utm_content=docs_inline).

Follow HitKeep on [X](https://x.com/gethitkeep), [Bluesky](https://bsky.app/profile/hitkeep.com), and [LinkedIn](https://www.linkedin.com/company/hitkeep).

Managed option

## Run HitKeep without the ops burden.

HitKeep Cloud runs the same single binary in region-pinned EU or US infrastructure, with managed updates and backups.

[Start free in HitKeep Cloud](https://cloud.hitkeep.eu/signup?utm_source=hitkeep_docs&utm_medium=website&utm_campaign=cloud_signup&utm_content=content_cta&plan=free&billing=monthly)[Self-host instead](https://hitkeep.com/guides/installation/)

[← OlderHitKeep 2.10.0: Custom Tracking Domains, Team Admin Pages, And Chart Preferences](https://hitkeep.com/blog/hitkeep-2-10-0/)[Newer →HitKeep 2.12.0: Team OIDC SSO, Invite-Aware Sign-In, And Routed Site Settings](https://hitkeep.com/blog/hitkeep-2-12-0/)