> ## 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.

# Make

> Connect HocDoc to Make: receive events with a custom webhook, and read, create, send and withdraw offers with the module Make a request and an API key.

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

* **HocDoc → Make:** A webhook from HocDoc starts a scenario, for example when an offer is accepted.
* **Make → HocDoc:** A scenario calls the HocDoc API with an API key.

> [!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).

## HocDoc → Make: a scenario starts on an event

**1. Create the webhook in Make**

Create a new scenario and add the app **Webhooks** as the first module. Choose the trigger **Custom webhook**. Choose **Add**, give it a name such as "HocDoc" and save. Make shows the webhook address. Copy it.

**2. Let the scenario wait**

Start the scenario with **Run once**. Make now waits for a request and remembers its structure.

**3. Add the endpoint in HocDoc**

In HocDoc, open **Settings**, then the **Integrations** tab. In the **Webhooks** card, choose **Add endpoint**. Paste the Make 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`. Make now knows the data structure of the event.

**5. Determine the structure with a real event**

A `ping` has no offer data (`data` is empty). So determine the data structure with a real event: reset the module (the module settings have an option to determine the data structure again), start the scenario with **Run once** again and trigger an event, for example by accepting a test offer. Then fields such as `data.offer.title` or `data.offer.recipient.email` are available in the following modules.

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 scenario: offer accepted

1. **Webhooks > Custom webhook** as the trigger.
2. A **filter** between the modules: `type` equal to `offer.accepted`. You need this if the endpoint receives several events.
3. A module as the target, for example **Google Sheets** with a new row (title, company, email, acceptance time, amount), **Slack** with a message, or your CRM with a deal.
4. For display, divide the amount by 100 with a formula such as `{{data.offer.value.amount}} / 100`.

Make decides the modules and fields in these apps.

### 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 **Custom webhook** module does not verify this signature by itself. This guide does not describe a check inside the scenario. The 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 webhook in Make, enter its address in the endpoint and delete the old one.

### Good to know

* By default Make answers `200` when the request was accepted. HocDoc needs 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)).
* Make deactivates a webhook that has not been connected to a scenario for more than 5 days, and it then answers `410`. After 5 finally failed deliveries in a row, HocDoc pauses the endpoint. Resume it in the **Webhooks** card.
* Events can arrive twice or out of order. Use the event `id` to spot duplicates.
* You see the history in the **Delivery log** card.

## Make → HocDoc: offers through the API

Here a scenario calls the HocDoc API with the module **HTTP > Make a request**.

**1. Create an API key**

Open **Settings**, **Integrations** tab, **API keys** card, **Create API key**. Give it a name such as "Make". Choose **Read only** if the scenario 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. Add the module**

Add the app **HTTP** and choose the action **Make a request**.

**3. Enter URL, method 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`, and choose the **Method**. Under **Headers**, add the header `Authorization` with the value `Bearer hd_live_...` (your key).

**4. Read the response**

Turn on **Parse response**. The fields of the JSON response are then available in the next modules. The data of the response is under `data`.

The key belongs in the header, never in the address or the body. With `401` the key is wrong, revoked or expired. With `403` the key can only read. In the **Advanced settings** of the module there is **Return error if HTTP request fails**: turn it on if the scenario should stop or enter error handling when the API returns an error.

### 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 scenario creates an offer from a template. Choose the method `POST`, the URL `https://app.hocdoc.com/api/v1/offers`, the `Authorization` header as above, `application/json` as the **Body content type**, and give this JSON as the body:

```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 module uses `POST https://app.hocdoc.com/api/v1/offers/{id}/send` with the `id` from the previous module. 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]
>
> If you put fields from earlier modules into the JSON body, watch for quotation marks and line breaks in the values. They make the JSON invalid. 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 Make come from the Make help: [Webhooks](https://help.make.com/webhooks) and [HTTP](https://apps.make.com/http). Make changes its interface from time to time. If names differ, the Make help applies.


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