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

# Zapier

> Connect HocDoc to Zapier: receive events by webhook, and read, create, send and withdraw offers with an API key.

You can connect HocDoc to Zapier today, without a dedicated app. There are two directions:

* **HocDoc → Zapier:** A webhook from HocDoc starts a Zap, for example when an offer is accepted.
* **Zapier → HocDoc:** A Zap calls the HocDoc API with an API key to read, create, send or withdraw offers.

Both ways use the app **Webhooks by Zapier**.

> [!NOTE]
>
> Only owners and admins create webhooks and API keys. More under [Settings](https://docs.hocdoc.com/en/guides/settings.md) and [Team and roles](https://docs.hocdoc.com/en/guides/team-and-roles.md). If you only need messages in Slack or Teams, you do not need Zapier: [Notifications and connections](https://docs.hocdoc.com/en/guides/notifications.md).

## HocDoc → Zapier: a Zap starts on an event

**1. Create the trigger in Zapier**

Create a new Zap. As the trigger, choose the app **Webhooks by Zapier** and as the **Event** **Catch Hook**. Choose **Continue**. Leave **Pick Off A Child Key** empty.

**2. Copy the webhook address**

In the **Test** tab, Zapier shows the webhook address. Copy it.

**3. Add the endpoint in HocDoc**

In HocDoc, open **Settings**, then the **Integrations** tab. In the **Webhooks** card, choose **Add endpoint**. Paste the Zapier address and choose the events, for example `offer.accepted`. The events are listed in the [webhook docs](https://docs.hocdoc.com/en/api/webhooks.md#events).

**4. Send a test event**

In the endpoint's row, choose **Send test**. HocDoc sends an event of type `ping`. Go back to the **Test** tab in Zapier and choose **Test trigger**. Zapier shows the fields of the event.

**5. Test with real data**

A `ping` has no offer data (`data` is empty). Trigger a real event, for example by accepting a test offer, and choose **Test trigger** in Zapier again. Then you find fields such as `data.offer.title` or `data.offer.recipient.email` for the next steps.

The webhook has a fixed format: `id`, `type`, `created_at`, `api_version` and `data` with `offer` and `event`. All fields are in the [webhook docs](https://docs.hocdoc.com/en/api/webhooks.md#body). Amounts are whole numbers in the smallest currency unit: `1250000` with `EUR` is 12,500.00 euros.

### Example: offer accepted

The Zap has two steps: **Webhooks by Zapier** (Catch Hook) as the trigger, then an action. If the endpoint receives several events, filter the Zap on `type` equal to `offer.accepted`.

| Goal | Action in Zapier | Fields to map |
| - | - | - |
| Row in Google Sheets | **Google Sheets**, event **Create Spreadsheet Row** | `data.offer.title`, `data.offer.recipient.company`, `data.offer.recipient.email`, `data.offer.accepted_at`, `data.offer.value.amount` |
| Slack message | **Slack**, event **Send Channel Message** | Text with `data.offer.title` and `data.offer.accepted_by.name` |
| Deal in a CRM | Action of your CRM, for example **HubSpot** or **Pipedrive** | Name from `data.offer.title`, contact from `data.offer.recipient` |

Zapier decides the exact names of the events and fields in these apps. If your CRM has its own connection in HocDoc, you do not need Zapier for it (**Integrations** tab, **Connections** card).

> [!WARNING]
>
> `value.amount` is in the smallest unit (cents). Divide it by 100 in a **Formatter by Zapier** step if you need euros.

### Security: signature and address

HocDoc signs every request following [Standard Webhooks](https://www.standardwebhooks.com/) with the headers `webhook-id`, `webhook-timestamp` and `webhook-signature`. The **Catch Hook** trigger of Zapier is not built for this and does not verify the signature. Zapier also offers **Catch Raw Hook**, which returns unparsed data and headers. This guide does not describe a signature check in a custom code step. The verification method is in the [webhook docs](https://docs.hocdoc.com/en/api/webhooks.md#verify-the-signature).

Without a check, the address is your protection: it is long and cannot be guessed. Treat it like a password. Do not share it and do not post it in tickets or chats. If you suspect it leaked, create a new trigger, enter its address in the endpoint and delete the old Zap.

### Good to know

* Zapier must answer with a `2xx` within 10 seconds. If a delivery fails, HocDoc tries up to 8 times over about a day ([Retries](https://docs.hocdoc.com/en/api/webhooks.md#retries)).
* After 5 finally failed deliveries in a row, HocDoc pauses the endpoint. Resume it in the **Webhooks** card. Events during the pause are not delivered later.
* Events can arrive twice or out of order. Use the event `id` to spot duplicates.
* You see the history in the **Delivery log** card.

## Zapier → HocDoc: offers through the API

Here a Zap calls the HocDoc API. You need an API key.

**1. Create an API key**

Open **Settings**, **Integrations** tab, **API keys** card, **Create API key**. Give it a name such as "Zapier". Choose **Read only** if the Zap only reads, and **Read and write** if it creates, sends or withdraws offers. Copy the key. It is shown only once. More: [Authentication](https://docs.hocdoc.com/api/authentication.md).

**2. Choose the action in Zapier**

Add **Webhooks by Zapier** as an action. As the **Event**, choose **GET** to read, or **Custom Request** for calls with a JSON body.

**3. Enter URL and header**

The base URL is `https://app.hocdoc.com/api/v1`. Enter the full address in **URL**, for example `https://app.hocdoc.com/api/v1/offers`. In the **Headers** section, add the header `Authorization` with the value `Bearer hd_live_...` (your key).

**4. Test**

Test the step. On success Zapier shows the response. With `401` the key is wrong, revoked or expired. With `403` the key can only read.

The key belongs in the header, never in the address or the body. The API reads it only from the `Authorization` header.

### Read offers

| Goal | Call |
| - | - |
| Check the key | `GET https://app.hocdoc.com/api/v1/workspace` |
| List of offers | `GET https://app.hocdoc.com/api/v1/offers` (optional `status` and `limit`, up to 100) |
| One offer | `GET https://app.hocdoc.com/api/v1/offers/{id}` |
| Timeline of an offer | `GET https://app.hocdoc.com/api/v1/offers/{id}/events` |

Responses come as `{ "data": ... }`. For lists, `next_cursor` points to the next page ([Pagination](https://docs.hocdoc.com/api/pagination.md)).

### Create and send an offer

With a **Read and write** key, a Zap creates an offer from a template. Choose **Custom Request**, method **POST**, URL `https://app.hocdoc.com/api/v1/offers`, the `Authorization` header as above and the header `Content-Type` with the value `application/json`. Put the JSON in the **Data** field:

```json theme={null}
{
  "template_id": "<ID of a template in your workspace>",
  "recipient": {
    "name": "Vera Kundin",
    "email": "vera@kunde.example",
    "company": "Kunde GmbH"
  },
  "title": "Website relaunch",
  "language": "en",
  "variables": { "company": "Kunde GmbH" }
}
```

`template_id` and `recipient` with `name` and `email` are required. Everything else is optional. With `variables` you answer the questions of the template by variable name. The response contains the offer as a draft with its `id`.

To send it, a second step calls `POST https://app.hocdoc.com/api/v1/offers/{id}/send` with the `id` from the previous step. The body may be empty. With `expires_on` (`YYYY-MM-DD`) you set the last day for acceptance. Without it, it is 14 days. Withdrawing works with `POST https://app.hocdoc.com/api/v1/offers/{id}/withdraw`.

The key acts as the person who created it. Role, approvals and plan apply as in the app. If the workspace requires an approval, the API does not send and answers `409` with `approval_required`.

> [!NOTE]
>
> Zapier puts fields from earlier steps into the body as text. A value with quotation marks or a line break makes the JSON invalid, and the API answers with an error. Write calls are limited to 30 per minute per key ([Rate limits](https://docs.hocdoc.com/api/rate-limits.md)). The `Idempotency-Key` header prevents a repeated call from creating an offer twice.

All fields, responses and errors are in the [API reference](https://docs.hocdoc.com/api/introduction.md).

## Sources for the menu names

The names in Zapier come from the Zapier help: [Trigger Zap workflows from webhooks](https://help.zapier.com/hc/en-us/articles/8496288690317-Trigger-Zaps-from-webhooks) and [Send webhooks in Zap workflows](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows). Zapier changes its interface from time to time. If names differ, the Zapier help applies.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.