- 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.
Only owners and admins create webhooks and API keys. More under Settings and Team and roles. If you only need messages in Slack or Teams, you do not need Zapier: Notifications and connections.
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.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.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: 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 ontype equal to offer.accepted.
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).
Security: signature and address
HocDoc signs every request following Standard Webhooks with the headerswebhook-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.
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
2xxwithin 10 seconds. If a delivery fails, HocDoc tries up to 8 times over about a day (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
idto 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.
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.Authorization header.
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 Zap creates an offer from a template. Choose Custom Request, method POST, URLhttps://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:
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.
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). The
Idempotency-Key header prevents a repeated call from creating an offer twice.