> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-hive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Incoming webhooks

> Send signed events from any system into Hive with an incoming webhook, directly or through Zapier or Make, and turn proposals and new clients into signals.

An incoming webhook gives any system a secure URL to push events into Hive. It is the quickest
way to connect a tool Hive has no connector for — including tools with no usable API, via Zapier
or Make. Hive verifies each event's signature, then feeds it into the same sensing pipeline as
every other connector.

## Create a webhook

<Steps>
  <Step title="Open Add a connector">
    In **Integrations → Connectors**, select **Add integration**, then **Incoming webhook** —
    "Signed events from any system."
  </Step>

  <Step title="Name it">
    Give it a label (up to 80 characters), for example "Ignition via Zapier".
  </Step>

  <Step title="Copy the URL and the signing secret">
    Hive shows the webhook URL and a **signing secret**.

    <Warning>
      The secret is shown **once**. "Save your signing secret now… This is the only time the
      secret is shown." Hive keeps only a sealed copy. If you lose it, delete the webhook and
      create a new one.
    </Warning>
  </Step>

  <Step title="Send a signed event">
    Configure your system to POST JSON to the URL with an `X-Hive-Signature` header. The tile
    shows **Awaiting events** until the first valid event arrives, then **Receiving**.
  </Step>
</Steps>

The first incoming webhook in a workspace needs an Owner or Admin, as with enabling any provider.

## What to send

* **Method:** `POST` to `https://<hive-api>/webhooks/incoming/<orgId>.<webhookId>` — copy the
  exact URL Hive shows you.
* **Body:** JSON, UTF-8, at most **64 KB**.
* **Header:** `X-Hive-Signature` — the lowercase hex HMAC-SHA256 of the **raw request body**,
  keyed with your signing secret.

Full details and code samples are in [Webhook signing](/developers/webhook-signing).

## Events Hive understands natively

Hive has a built-in contract for proposal and CRM tools. A body matching one of these types is
mapped straight into Business Brain facts and signals, with no AI involved:

| `type` | Meaning | `amount` |
| - | - | - |
| `proposal.created` | A proposal was sent | Required |
| `proposal.won` | A proposal was accepted | Required |
| `client.created` | A new client was set up | Optional |

```json theme={null}
{
  "type": "proposal.won",
  "entity": "Acme Ltd",
  "sourceTool": "Ignition",
  "amount": { "value": 45000, "currency": "GBP" },
  "occurredAt": "2026-09-28T10:15:00Z",
  "eventId": "ign_8812"
}
```

| Field | Rules |
| - | - |
| `entity` | The client or company name. 1–200 characters, not blank. |
| `sourceTool` | Where the event came from, e.g. `Ignition`. 1–80 characters. |
| `amount` | `value` in major units (45000 = £45,000), non-negative; `currency` a 3-letter ISO code. |
| `occurredAt` | Optional ISO date or timestamp. An implausible date falls back to the time received. |
| `eventId` | Optional stable id from your automation, up to 128 characters. |

Extra fields are ignored, so an automation that sends more than this still works.

**Any other valid JSON** is accepted too, and goes through Hive's general ingest path.

## Bridge a tool through Zapier or Make

Many proposal and practice tools — Ignition, Go Proposal, Figsflow — have no API Hive can
connect to directly. Bridge them:

<Steps>
  <Step title="Trigger">
    In Zapier or Make, trigger on the tool's event (for example "Proposal accepted").
  </Step>

  <Step title="Build the body">
    Map the fields into the JSON above: `type`, `entity`, `sourceTool`, `amount`.
  </Step>

  <Step title="Sign it">
    Add a code step that computes the HMAC-SHA256 of the exact body you will send, and put it in
    `X-Hive-Signature`. See the Node.js and Python samples in
    [Webhook signing](/developers/webhook-signing).
  </Step>

  <Step title="POST it">
    Send the body to your webhook URL. A `202` response means Hive accepted it.
  </Step>
</Steps>

## Responses

| Status | Meaning |
| - | - |
| `202` `{"received": true}` | Accepted. |
| `202` `{"received": true, "deduplicated": true}` | An identical signed body was already received; not processed twice. |
| `400` `invalid_input` | The body is not valid UTF-8 JSON. |
| `401` `invalid_signature` | Missing or wrong signature — or the webhook does not exist. Both give the same answer, on purpose. |
| `404` `not_found` | The URL is malformed. |
| `413` `payload_too_large` | The body is over 64 KB. |
| `503` | Temporarily unavailable, or the same delivery is still being processed. Retry later. |

## Replay and delete

* Proposal events are kept as receipts, so a repeat of the same signed delivery is recognised and not processed twice.
* Delete a webhook to stop accepting events at its URL immediately.

## Related

<CardGroup cols={2}>
  <Card title="Webhook signing reference" icon="code" href="/developers/webhook-signing">
    Code samples in curl, Node.js and Python.
  </Card>

  <Card title="Accounting and client services" icon="briefcase" href="/use-cases/accounting-and-client-services">
    Proposal-to-client workflows.
  </Card>
</CardGroup>