hivy
Documentation
DocumentationAutomations

HTTP webhooks

Give an outside system a private URL that starts an agent session when it receives an authenticated POST request.

Any system that can send a POST request can start a Hivy agent through an HTTP webhook. The body carries request-specific data; the webhook's saved instructions tell the agent what to produce in its team.

Video placeholder

Call a protected Hivy webhook

Create a webhook trigger with a shared secret on camera; copy its URL, send a small JSON POST request with an Authorization bearer header, and open the session that request starts.

Create the webhook

  1. 1

    Choose its team and agent

    Pick the team for new sessions and an agent from that team.

  2. 2

    Write stable instructions

    Explain what every request should make the agent do; each body supplies the data that changes.

  3. 3

    Create and store a shared secret

    Make the value long and unique, then save it in the caller's secret manager. Hivy keeps a protected hash and can't recover the original.

  4. 4

    Copy the unique URL

    Open the new webhook's detail page and copy its POST URL.

Image placeholder

Webhook URL, status, and last run

Keep the webhook detail page readable, including the URL and Copy action, latest run link, team, agent, instructions, and enabled status. No real shared secret should appear.

Send a small POST request

Put the shared secret in the Authorization header as a bearer token. An agent can usually read a JSON object more reliably than an unstructured body, although Hivy accepts either; the body must stay below 256 KB.

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Authorization: Bearer YOUR_SHARED_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"customer-123","event":"trial_ended"}'

Hivy also reads the secret from X-Api-Key or X-Webhook-Secret. Don't use the supported secret query parameter unless your caller can't set headers, because URL logs may capture it.

Treat the response as acceptance

A 200 response means Hivy accepted the request for asynchronous processing, not that the agent finished. Open the webhook's latest session for the result; the HTTP response won't contain it.

Keep sensitive data out of the task

Hivy redacts JSON fields whose keys contain password, secret, token, API key, credential, or authorization. Redaction can't make a loose data policy safe, so send a reference or the smallest required value instead of a credential.

The URL identifies the webhook, but every call still needs the shared secret. To rotate that secret, create a replacement webhook and move the caller before you delete the old one.

Disable requests without deleting the setup

Turn the webhook off when calls need to stop for a while; Hivy rejects requests to it and doesn't start the agent. Workspace owners and admins can edit, disable, or delete an existing webhook.