Skip to main content
HocDoc can call your server when something happens to an offer. You add an endpoint (an HTTPS address) in the app, choose the events you want, and HocDoc sends a signed POST request with a JSON body for each event. Webhooks use the same objects as the API: the body contains the offer as returned by GET /api/v1/offers/{id} and the timeline entry as returned by GET /api/v1/offers/{id}/events. The machine-readable contract is the webhooks section of the OpenAPI description at https://app.hocdoc.com/api/v1/openapi.json.

Set up an endpoint

In the app: Settings, then the Integrations tab, card Webhooks, button Add endpoint. Owners and admins can manage endpoints. A workspace can have up to 5 endpoints. One account can set up endpoints in up to 20 workspaces.
  • Enter the address and choose the events.
  • The secret (whsec_…) is shown exactly once. Store it safely, you need it to verify signatures. If you lose it, generate a new one (“Geheimnis neu erzeugen”). The old secret stops working immediately, and messages rejected in the meantime are retried automatically until the new secret is entered at the receiver. The two secrets are never valid at the same time.
  • “Test senden” sends a ping event to the endpoint, so you can check the address and your signature check.

Requirements for the address

  • https only, on the default port 443.
  • A public host name. IP addresses, credentials in the address (user:password@) and internal names are rejected.
  • The name must resolve to public addresses only.
  • Redirects are not followed. A 3xx response counts as a failure.
  • Hosts on hocdoc.com, vercel.app and supabase.co are not accepted. The same goes for a custom domain that a workspace uses for its offer pages.

Events

offer.expired is detected every 15 minutes and sent out about two minutes later, so it arrives up to about 20 minutes after expires_at. domain.updated has no offer. It is sent when a domain is added, set up, stops working, is removed or expires after 14 days without setup, and not when a status check finds the same status again. It is sent to your own endpoints only, not to Slack, Teams or CRM channels. In the event list of an endpoint it is called “Domain status changed”. For new endpoints it is not preselected. Its body is described under Body of domain.updated. Status changes of a sender domain are picked up by the schedule and can arrive up to about 20 minutes late. There is no offer.declined event: recipients cannot decline an offer in the product today. New event types may be added. Ignore types you do not know, and answer them with 2xx.

Request

These three headers, Content-Type and User-Agent are the contract. HocDoc adds no tracing or other headers of its own.

Body

Things to know:
  • data.offer is read shortly after the event, when the webhook is prepared. It can already reflect a later change. For offer.sent followed quickly by offer.accepted, both bodies may show status: accepted. Rely on type and data.event for what happened.
  • data.event.type is the type of the timeline entry. For offer.first_viewed it is viewed.
  • data.event.data depends on the type:
  • data.offer.choice is what the recipient chose: one package per pricing section with a choice, the add-ons they ticked and the totals. It is part of the offer object, so every webhook with data.offer carries the field. It is null if the offer has no pricing section with a choice (a single fixed price) or nothing has been chosen yet, which is the usual case before offer.accepted. With several signers the first signer chooses: from their offer.signed on, the choice is set. After an offer is sent again, the choice starts at null. Amounts are whole numbers in the smallest currency unit, like value. billing_note is the billing wording next to the price (for example “one-time” or “per month”), empty if there is none. There is one total per combination of currency and billing wording: a one-time price and a monthly price are never added up. Names, prices and wording are frozen at the time of the choice and are the same as in the proof of acceptance and the certificate. sections has one entry per pricing section with a choice (more than one package or at least one add-on), in the order of the offer. A pricing section with a single fixed price has no entry, and its price is not part of totals. totals are the sums across the sections listed in sections, not across the whole offer. value is unchanged: one number per offer. Once the choice is set (on acceptance, with several signers from the first signer’s offer.signed on), it counts the chosen package of the first visible pricing section plus the chosen add-ons with the same currency and billing wording as that package. Before that it counts the preselected package and add-ons. If that section is a single fixed price, value is that price. value and choice.totals can therefore differ in both directions: choice.totals covers all pricing sections with a choice and every billing wording, but no fixed-price section.
  • For ping, data is an empty object.
  • New fields may be added at any time. Ignore fields you do not know.
  • The body is at most 64 KiB.

Body of domain.updated

Nothing else is sent: no reason for an error, no DNS records, no IDs.

What is never sent

The token of the public link, acceptance codes, IP addresses and browser identifiers of recipients, the content of an offer (sections, texts, packages and add-ons that were not chosen), the message to the recipient, signatures, internal IDs, and anything about other workspaces. Of the content, only the choice of the recipient is sent: the chosen package and add-ons with name, price and billing wording, see data.offer.choice.

Verify the signature

Always verify the signature before you trust a request. HocDoc signs following the Standard Webhooks specification, so you can use one of its libraries or the few lines below.
  1. Take the secret of the endpoint, remove the prefix whsec_, and base64-decode the rest. These bytes are the key.
  2. Build the signed content: <webhook-id>.<webhook-timestamp>.<raw body>. Use the raw bytes of the request body, exactly as received. Do not parse and re-serialize the JSON first.
  3. Compute the HMAC-SHA256 of the signed content with the key and base64-encode it.
  4. webhook-signature contains one or more entries separated by spaces. Accept the request if any entry with the version v1 equals your result. Compare in constant time.
  5. Reject requests whose webhook-timestamp is more than 5 minutes away from your clock. This limits replays.
The header is a list so that a secret can be replaced later without breaking receivers. Today it has one entry.

Node.js

With Express, read the raw body for this route (express.raw({ type: "application/json" })) and parse the JSON only after the check.

Python

Test vectors

Use these to check your implementation. The timestamps are in the past, so skip the tolerance check for them. A ping as HocDoc sends it: The reference vector of the Standard Webhooks specification:

Respond

Answer with any 2xx status within 10 seconds. The response body is ignored. Do slow work after you have answered. Everything else counts as a failed attempt: any other status (including 3xx), no response within 10 seconds, a connection or TLS error.

Retries

A failed delivery is retried with growing pauses, 8 attempts in total over about a day: After the 8th failed attempt the delivery counts as failed. You can send it again from the delivery log in the app (“Erneut senden”), up to 5 times. A resend carries the same webhook-id and the same body. A resend is not possible while the endpoint has 1,000 open deliveries. A resend is also rejected while the endpoint is paused. Resume the endpoint first. Deliveries cancelled by a pause are listed as failed and can be sent again after resuming. The delivery log in the app shows the last 50 deliveries of the workspace. Only deliveries listed there can be sent again. For anything older, use the API to catch up.

Automatic pause

After 5 deliveries in a row that failed for good, the endpoint is paused automatically and its open deliveries are cancelled. The app shows “Automatisch pausiert”. Fix the receiver, then resume the endpoint in the app. Events that happen while an endpoint is paused are not delivered later. Use the API to catch up.

Order and duplicates

  • Order is not guaranteed. Events can arrive out of order, for example when one of them is retried. Use data.event.sequence (the position in the timeline of the offer) or created_at if you need the order.
  • Events can arrive more than once. Store the webhook-id values you have processed and ignore repeats.
  • Each endpoint receives each event independently. One failing endpoint does not hold back the others.

Limits

Deliveries above 60 per minute are not dropped, they wait. Each workspace has its own share: the volume of another workspace does not delay your deliveries. Workspaces take turns, and the one that has waited longest goes first. A workspace that sets up its first endpoint joins at the back of the line, never ahead of workspaces that are already waiting. This is not a hard guarantee on delivery time. Sending goes round-robin per workspace, so the time your workspace waits grows at most with the number of workspaces that are waiting at the same moment. No workspace is skipped, but when very many workspaces have events waiting at once, all of them wait longer. The limit of 20 workspaces counts the workspaces in which your account created endpoints, paused ones included. If you need webhooks in more workspaces, another owner or admin of that workspace can set them up. When you delete the last endpoint of a workspace, events of that workspace that were still waiting to be sent out are dropped. An endpoint that already has 1,000 open deliveries (waiting or being retried) does not get more queued. Further deliveries to it are recorded as failed in the delivery log without an attempt (“Nicht eingereiht”) and can be sent again from there once the endpoint has room. While it has 1,000 open deliveries, sending a delivery again from the delivery log is rejected as well. If 1,000 events of a workspace are waiting to be sent out at the same moment, further events are not turned into webhooks. Neither limit is reached in normal use. Use the API to catch up.