---
title: "Signed webhooks"
description: "Connect Hoplite events to your workflow engine with signed, recoverable webhook deliveries."
canonical_url: "https://hoplite.sh/docs/factory/webhooks"
markdown_url: "https://hoplite.sh/docs/factory/webhooks.md"
---

# Signed webhooks
URL: /docs/factory/webhooks
LLM index: /llms.txt
Description: Connect Hoplite events to your workflow engine with signed, recoverable webhook deliveries.
Related: /docs/factory/events, /docs/api/createWebhook

# Signed webhooks

Connect your workflow engine to Hoplite state changes with signed webhooks. Subscribe a public HTTPS endpoint to receive events without maintaining a stream. To trigger work *into* Hoplite, use an [automation webhook](/docs/automations#trigger-from-a-webhook).

## Create a subscription

Call [Create webhook](/docs/api/createWebhook) with the destination URL, project scope, and event types. Creation requires `webhook:create`, `webhook:read`, and `thread:read`. Delivery rechecks the account’s current read grants and project scope. Save the returned signing secret securely because replayed operation receipts omit it.

The factory example can create a subscription when `HOPLITE_WEBHOOK_URL` and `HOPLITE_WEBHOOK_SECRET_FILE` are configured. The destination must already be ready to verify incoming requests.

Subscriptions belong to the stable service account. Rotating or revoking an individual credential does not stop them; disable the account, remove its grants, or pause the subscription to stop delivery. Paused subscriptions do not accumulate new deliveries.

## Verify a delivery

Verification uses the exact raw request body, before parsing or reserializing JSON:

1. Read the timestamp and `v1` signatures from `hoplite-signature`.
2. Reject timestamps outside your accepted freshness window.
3. Compute HMAC-SHA256 with the signing secret over the timestamp, a period, and the raw body bytes.
4. Compare the computed value to a `v1` signature in constant time.
5. Deduplicate by `hoplite-event-id` before applying the event to your workflow.

During secret rotation, deliveries include signatures from both secrets for 24 hours. Install the new secret before removing the old one.

## Delivery and retry behavior

| Condition | Behavior |
| --- | --- |
| Request takes over ten seconds | The attempt times out |
| Transient failure | Retried within 24 hours of delivery creation |
| Subscription paused | Pending deliveries remain, but the retry window continues to elapse |
| Delivery reaches 24 hours | Marked failed, including while paused or unauthorized |
| Manual redelivery | Starts a new retry window |
| Completed delivery metadata | Retained for 30 days after completion |

Persist receipt of an event before acknowledging it, and process longer work asynchronously so the request can finish within the timeout. Delivery retries mean the same event can arrive more than once.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).