Webhooks

What webhooks do

Webhooks send signed HTTPS requests from Hoko to a server you control when a subscribed workspace action is recorded. Use them to notify your own integrations. Logs show recorded activity even when no webhook is configured.

Access and availability

Open Dashboard → Integrations → Webhooks. The feature must be enabled in your deployment. Access requires an active account with the Owner or Workspace Admin role. The workspace must have an active collection. Blocked or removed memberships do not qualify.

Webhooks cover the whole workspace, not just the selected collection. Business or above is required to create, verify, test, and receive webhooks. API keys do not grant access to this dashboard: there is currently no public webhook-management API.

Active webhook allowances per workspace are Business 10, Enterprise 20, and Elite 40. Free and Pro have no webhook allowance. Storage allows five additional replacement slots (15/25/45 total), including pending and disabled entries. Delete unused entries to free slots. After a downgrade, the oldest active webhooks within the new allowance remain eligible; excess configurations are preserved without delivery.

On downgrade, sending is suspended but configuration and retained history remain accessible to the Owner and Workspace Admin. You can still disable or delete webhooks. Upgrading to an eligible plan allows active webhooks to receive new events again; disabled webhooks stay off until you verify and enable them. Missed events are not replayed, and already-sent requests cannot be recalled.

Create and verify a webhook

With data export access (Business or above), select visible webhooks and choose Download selected. The button shows the selection count. The JSON download includes their IDs, names, subscribed events, statuses, and creation/verification times. It excludes destinations, signing secrets, payloads, and delivery attempts. Search and filters limit which selected webhooks are included.

  1. Prepare a public HTTPS receiver using the developer guide and its tested receiver example.
  2. Select Create webhook, enter a webhook name and receiver URL, choose the events you need, and paste an existing whsec_ signing secret or use the shuffle control to generate one. Leave the field blank and Hoko will generate one when you create the webhook.
  3. Create the pending webhook. Copy its signing secret immediately and store it only in your receiver's server-side secret storage. It cannot be reopened.
  4. Make the receiver verify the signature and return the exact challenge response for endpoint.verification, as described in the developer guide.
  5. Select Verify webhook. Only a successfully verified, active webhook receives subscribed events.
  6. Send a test and inspect its delivery result. A test is a real outbound request to your receiver; handle endpoint.test without triggering customer business actions.

If you lose the secret, create a replacement webhook. Never paste secrets into support messages, browser code, analytics, or logs.

Events and payloads

Select events from the current resource/action catalog. Names use dots, with camelCase where a name needs multiple words: for example link.destination.updated and apiKey.revoked. Global profile.* activity is excluded from workspace subscriptions. Verification and test messages are operational messages, not subscription choices.

Every subscribed workspace event uses the same thin payload: id, type, created, and data containing only the affected record id and workspaceId. This includes lead.created and sale.created; fetch record details through the relevant API when available. See the payload contract.

Delivery results and limits

Delivery makes one immediate, best-effort attempt. Hoko does not retry automatically or guarantee ordering. A failed receiver does not undo an accepted change in Hoko. Bulk changes may exhaust the request's delivery budget and leave some deliveries pending.

Immediate delivery supports the plan’s active webhook allowance, up to 40 webhooks. Owner and Workspace Admin actions allow 10 verification attempts per hour and 30 test sends per hour. Receiver requests are limited to 64 KiB with a three-second receiver budget; database work adds time. If rate limited, wait for the indicated retry interval. Delivery history is retained for the workspace lifetime, including after a webhook is deleted. Attempts do not consume tracked-event allowance; there is no monthly delivery quota or overage billing.

Inspect results in Webhooks and related Logs. From a log row's More options menu, an Owner or Workspace Admin on an active Business or higher plan can resend a pending, failed, or Unconfirmed delivery. Hoko waits five minutes before allowing an Unconfirmed delivery to be resent. A pending delivery uses its existing first attempt; a failed or old Unconfirmed delivery adds a new attempt. Every send uses a new signature timestamp and keeps the original event ID. Unconfirmed means Hoko saved no terminal result, so the receiver may have received the earlier request. Your receiver must verify signatures and durably deduplicate event IDs before applying business effects.

View delivery history

The webhook side sheet shows the receiver URL and the 10 most recent delivery attempts. Choose See all deliveries from the webhook row's More options menu or from the side sheet to open the complete history for that webhook. The dedicated delivery page loads history in pages and lets you sort and filter the attempts without loading the entire history at once.

Disable, replace, or delete a webhook

Disabling stops new fan-out, but cannot recall a request already sent. To change the receiver URL, first disable the webhook, select Change receiver URL, save the new public HTTPS URL, and select Verify webhook. The webhook returns to pending verification while Hoko keeps its ID, delivery history, and signing secret. Hoko sends a fresh challenge to the new destination before activation. To re-enable a disabled webhook without changing its URL, select Verify and enable. To change the webhook name, subscribed events, or signing secret, create and verify a replacement, then disable the old webhook. If both are active, your receiver may receive the same event through both. Delete the old webhook only when you no longer need its configuration; deletion clears its destination and signing secret but keeps its delivery history.

Select Delete webhook when you no longer need its configuration. Deletion hides the webhook from management, preserves its name and delivery history, and erases its signing material. The workspace activity log is separate; deleting a webhook does not erase ordinary log facts. Deleted webhooks cannot deliver or be resent.

Troubleshooting

  • Missing tab or page: check the workspace, your Owner or Workspace Admin role, and whether the deployment has the feature enabled. An upgrade does not bypass these checks. If the page reports a plan suspension, Business or above is required for sending.
  • Verification fails: check the signing secret, exact raw request bytes, timestamp tolerance, and exact challenge response.
  • Destination rejected: use public HTTPS. Private/local addresses and redirects are not supported; never bypass receiver signature checks.
  • No event arrives: check the webhook is active, the event is selected, the action happened in this workspace, and the delivery result. Old activity is not sent retroactively.

See developer documentation for signatures, schemas, and receiver security.