Manage subscriptions

Webhook endpoints and their signing secrets are managed in the dashboard today. There is no public API for subscription CRUD yet — no /v1 endpoint creates, lists, or deletes webhook subscriptions. Create and maintain them in the dashboard, and verify every delivery in your handler.

Create an endpoint

In the dashboard, add an endpoint with the HTTPS URL your handler listens on and the events you want delivered. When you create it, the dashboard shows the endpoint's signing secret — prefixed whsec_ — once. Copy it into your handler's configuration then; you can't read it back later.

Each endpoint has its own secret. Every delivery to that endpoint is signed with it, and your handler verifies against it. See Verify signatures for the exact scheme.

Rotate a secret

Rotate a secret if it may have leaked, or on a regular schedule. In the dashboard:

1. Generate a new signing secret for the endpoint.
2. Update your handler to verify against the new secret.
3. Confirm deliveries are verifying, then revoke the old secret.

Because the secret is per-endpoint, rotating one endpoint's secret never affects another.

Test a delivery

Send a test event to the endpoint from the dashboard and confirm your handler:

• Verifies the signature against the endpoint's secret before trusting the body — see signatures.
• Returns a 2xx quickly, then processes asynchronously. Slow handlers trigger retries.
• Dedupes on id. Retries can duplicate a delivery; your handler must be idempotent on the event id.

If your handler fails or times out, Hannu retries on a backoff schedule — 1, 5, 30, 120, then 600 minutes — before the delivery dead-letters. Test that a transient failure followed by a retry lands exactly one processed event.

Next

• Verify signatures — the signing scheme and a verification snippet.
• Event catalogue — which events you can subscribe to.