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:
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.tsAfter 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:
webhook-id: <event_id>
webhook-timestamp: <unix_seconds>
webhook-signature: v1,<base64_hmac>Compute HMAC-SHA256 over:
webhook-id + "." + webhook-timestamp + "." + exact_raw_bodyUse 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.