Receive link.created webhooks

Verify Hoko link.created deliveries and record durable, minimized receipts.

What this guide covers

This guide covers a customer-owned HTTPS receiver for Hoko's link.created event. Use the receiver example as the reference source. The receiver calls no Hoko database and does not create a second webhook contract.

The receiver must bind the configured endpoint and workspaceId to the event. A provider or automation platform may call the receiver only after it has been configured through the existing Hoko webhook flow.

Configure the receiver

Create the pending webhook in Hoko first. Select link.created, enter the receiver's public HTTPS URL, and copy the endpoint ID, workspace ID, and one-time signing secret into server-side environment variables. Then start the receiver and select Verify webhook in Hoko. Hoko sends the signed endpoint.verification challenge only after the endpoint exists.

The reference server uses these variables:

Code sh
HOKO_ENDPOINT_ID=<endpoint-id> \
HOKO_WORKSPACE_ID=<workspace-id> \
HOKO_WEBHOOK_SECRET=whsec_... \
HOKO_RECEIPTS_DB=./var/hoko-webhook-receipts.sqlite \
bun run src/main.ts

After verification succeeds, create one link in the same workspace. Inspect the redacted receipt, then use Hoko's explicit resend action to confirm that a repeated event returns a duplicate receipt. Do not create the link before endpoint verification.

Verify the raw request

Read the exact request bytes before parsing JSON. The sender supplies:

Code http
webhook-id: <event_id>
webhook-timestamp: <unix_seconds>
webhook-signature: v1,<base64_hmac>

Compute HMAC-SHA256 over:

Code text
webhook-id + "." + webhook-timestamp + "." + exact_raw_body

Use the configured whsec_ secret and compare equal-length signatures with a timing-safe comparison. Reject a missing header, malformed timestamp, invalid signature, or body larger than 64 KiB.

Accept timestamps only within 300 seconds of the receiver clock. Verify the body id equals webhook-id, the body type is link.created, and data.workspaceId equals the configured workspace. Verify the endpoint ID before processing an endpoint challenge.

Store a minimized receipt

After signature, endpoint, workspace, and schema checks pass, write one durable receipt keyed by (workspaceId, webhook-id). Store the event ID, raw-body SHA-256 digest, request ID, endpoint ID, event type, and received time. Keep the receipt small. Do not store the raw body, signature, secret, customer data, destination query, or full response.

Keep a replay ledger for at least the 300-second timestamp window and retain the event ID for the lifetime of the receiver's operational history. A repeated event with the same digest returns 2xx as a duplicate. The same event ID with a different digest returns a conflict for operator review.

Return a 2xx response quickly after the receipt is durable. The receipt proves that the receiver accepted the event. It does not prove that a later business action completed.

Delivery states and resend

Hoko sends one bounded request-time attempt and records pending, failed, or unknown outcomes when the attempt cannot finish with a final result. Hoko does not run an automatic background worker and does not promise exactly-once delivery.

Treat unknown as possibly delivered. Deduplicate by webhook-id before applying any side effect. An operator may use the existing explicit resend action after inspecting the receipt. A resend has a new signature timestamp but keeps the event identity, so the receiver must remain idempotent.

Local acceptance

Use a disposable receiver and local Hoko database. Test valid and invalid signatures, a stale timestamp, a replay, a body-size rejection, a wrong workspace, a wrong endpoint, a malformed event, and concurrent duplicate delivery. Record only redacted receipts and request IDs.