- 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.
Only owners and admins create webhooks and API keys. More under Settings and Team and roles.
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.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.id, type, created_at, api_version and data with offer and event. All fields are in the webhook docs. Amounts are whole numbers in the smallest currency unit: 1250000 with EUR is 12,500.00 euros.
Example scenario: offer accepted
- Webhooks > Custom webhook as the trigger.
- A filter between the modules:
typeequal tooffer.accepted. You need this if the endpoint receives several events. - 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.
- For display, divide the amount by 100 with a formula such as
{{data.offer.value.amount}} / 100.
Security: signature and address
HocDoc signs every request following Standard Webhooks with the headerswebhook-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.
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
200when the request was accepted. HocDoc needs a2xxwithin 10 seconds. If a delivery fails, HocDoc tries up to 8 times over about a day (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
idto 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.
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.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
Responses come as
{ "data": ... }. For lists, next_cursor points to the next page (Pagination).
Create and send an offer
With a Read and write key, a scenario creates an offer from a template. Choose the methodPOST, 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:
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.
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). The
Idempotency-Key header prevents a repeated call from creating an offer twice.