Zapier

Run the private Hoko link actions in Zapier with API-key authentication.

Get the private app preview

The Zapier app runs in Zapier and calls Hoko's unversioned resource REST API. It needs no dedicated Hoko job runner, queue, scheduler, or background service.

The package is a private preview. A Zapier import, connection, workflow run, and marketplace review remain external acceptance work.

Configure the connection

Create a Hoko API key with linksRead, linksWrite, webhooksRead, and webhooksWrite. Store it in Zapier's secret connection field. Use https://api.hoko.to as the Hoko origin.

The API key selects one Hoko workspace. The connection test calls GET /links?take=1. The app does not expose a workspace ID field. Hoko binds each operation to the workspace selected by the key.

Use the actions

The private preview exposes two actions:

ActionRequired valuesResource routeEngine metadata
Create LinkCollection ID, Destination URL, External IDPOST /linkslinks.createFromApi
Find LinkExternal IDGET /links?externalId=...links.list

Pass a stable source record ID as External ID to Create Link. The field is required. Use the same exact value in Find Link. Keep the value namespaced and at or below 255 characters.

The create response contains the Hoko link ID, short URL, destination URL, collection ID, and external ID. The lookup reads a list, filters it to exact external ID matches, and returns one item to Zapier only when exactly one match exists. Zero matches return no item. Multiple matches fail for operator review.

Successful action output also includes requestId. When Hoko sends valid rate headers, it includes rateLimit with limit, remaining, and resetAt. Errors include a safe requestId; rate-limited errors may include Retry-After. Malformed rate values are omitted.

Signed event triggers (activation blocked)

The private preview exposes REST hook triggers for link.created and sale.created. Enter the public Workspace ID from Hoko Settings, a pre-enrolled active relay endpoint ID, and its exact HTTPS relay URL. The API key must belong to that workspace. Keep the Hoko webhook signing secret in the private connection secret field; it is never returned in trigger output.

The callback verifies the exact raw request body, webhook-id, timestamp, and HMAC before returning one item. It checks the event ID, event type, and workspace ID against the subscription. Zapier uses the stable event ID for retry deduplication. The delivery model is bounded and at-least-once. Hoko does not promise exactly-once delivery.

The trigger output contains the shared envelope fields: event ID, event type, created time, event data ID, and workspace ID. The adapter does not add sale amounts or other private fields that are absent from the signed envelope.

Subscribe and unsubscribe verify endpoint ownership, event selection, name, and URL binding before deleting the endpoint. Scope failures, revoked keys, rate limits, disabled endpoints, invalid signatures, stale timestamps, and binding mismatches return safe errors with request IDs.

Activation has a callback contract gap. Zapier Platform Core 19.2.0 requires a REST hook perform function to return an item array and provides no raw HTTP response override. Hoko verification requires the exact {"challenge":"..."} JSON response, so the direct callback cannot activate an endpoint through webhooks.verify. Keep the preview private and actions-only until the customer-owned relay contract is pre-enrolled and wired to the subscription path. The relay must answer the challenge, preserve exact signed bytes and headers when forwarding to Zapier, durably deduplicate event IDs, and enforce bounded enrollment, revocation, and rate handling. It must not weaken HMAC verification or add an Hoko worker.

Reconcile before retrying

Link creation has no request idempotency guarantee. The caller must store the source account, foreign record ID, payload fingerprint, request ID, and returned Hoko link ID in durable workflow state.

The action checks the exact external ID before creating, then verifies the returned link with the same lookup. If the create acknowledgement is lost, it performs one safe read by the exact external ID. It reports a created link only when exactly one result matches the external ID, destination, and collection. An empty or duplicated result, a malformed read, or a network error returns a halted outcome for operator reconciliation. The action never sends a second create. Zapier does not provide Hoko's mapping or serialization policy. Make the workflow the exclusive owner of each source mapping and disable automatic replay where the host allows it.

The app sends one request ID per Hoko operation. It does not follow redirects, limits each request to 10 seconds and 1 MB, and preserves bounded rate metadata. Treat 401 as an invalid key, 403 as a missing scope, and 429 as a rate limit. Respect Retry-After. Keep request IDs and rate-limit headers in redacted logs.

Keep the preview private

The first app slice excludes analytics, API-key management, billing, profile uploads, destructive workspace actions, and public directory publication. Zapier's remote MCP Client remains a separate manual connection path.

Use disposable local Hoko fixtures for acceptance. Do not use production, staging, or Playground as a test database. Record the provider import, connection test, create, exact lookup, denied scope, revoked key, rate-limit response, ambiguous write handling, and cleanup before calling the app verified.