- HocDoc → Make: Ein Webhook von HocDoc startet ein Szenario, zum Beispiel wenn ein Angebot angenommen wird.
- Make → HocDoc: Ein Szenario ruft die API von HocDoc mit einem API-Key auf.
Nur Inhaber und Admins legen Webhooks und API-Keys an. Mehr dazu unter Einstellungen und Team und Rollen.
HocDoc → Make: ein Szenario startet bei einem Ereignis
1
Webhook in Make anlegen
Lege ein neues Szenario an und füge als erstes Modul die App Webhooks hinzu. Wähle den Trigger Custom webhook. Wähle Add, vergib einen Namen wie „HocDoc“ und speichere. Make zeigt die Webhook-Adresse. Kopiere sie.
2
Szenario warten lassen
Starte das Szenario mit Run once. Make wartet jetzt auf eine Anfrage und merkt sich ihren Aufbau.
3
Endpunkt in HocDoc anlegen
Öffne in HocDoc Einstellungen, dann den Reiter Integrationen. In der Karte Webhooks wählst du Endpunkt hinzufügen. Füge die Make-Adresse ein und wähle die Ereignisse, zum Beispiel
offer.accepted. Die Ereignisse stehen in der Webhook-Doku.4
Testereignis senden
Wähle in der Zeile des Endpunkts Test senden. HocDoc schickt ein Ereignis vom Typ
ping. Make kennt nun die Datenstruktur des Ereignisses.5
Struktur mit einem echten Ereignis bestimmen
Ein
ping hat keine Angebotsdaten (data ist leer). Bestimme die Datenstruktur deshalb mit einem echten Ereignis: Setze das Modul zurück (in den Einstellungen des Moduls gibt es die Option, die Datenstruktur neu zu bestimmen), starte das Szenario wieder mit Run once und löse zum Beispiel durch die Annahme eines Testangebots ein Ereignis aus. Danach stehen Felder wie data.offer.title oder data.offer.recipient.email in den folgenden Modulen zur Verfügung.id, type, created_at, api_version und data mit offer und event. Alle Felder stehen in der Webhook-Doku. Beträge sind ganze Zahlen in der kleinsten Währungseinheit: 1250000 mit EUR sind 12.500,00 Euro.
Beispiel-Szenario: Angebot angenommen
- Webhooks > Custom webhook als Trigger.
- Ein Filter zwischen den Modulen:
typegleichoffer.accepted. Das brauchst du, wenn der Endpunkt mehrere Ereignisse bekommt. - Ein Modul als Ziel, zum Beispiel Google Sheets mit einer neuen Zeile (Titel, Firma, E-Mail, Annahmezeit, Betrag), Slack mit einer Nachricht oder dein CRM mit einem Deal.
- Rechne den Betrag für Anzeigezwecke mit einer Formel durch 100, zum Beispiel
{{data.offer.value.amount}} / 100.
Sicherheit: Signatur und Adresse
HocDoc signiert jede Anfrage nach Standard Webhooks mit den Headernwebhook-id, webhook-timestamp und webhook-signature. Das Modul Custom webhook prüft diese Signatur nicht von selbst. Eine Prüfung im Szenario beschreibt diese Anleitung nicht. Das Verfahren steht in der Webhook-Doku.
Ohne Prüfung ist die Adresse dein Schutz: Sie ist lang und nicht zu erraten. Behandle sie wie ein Passwort. Gib sie nicht weiter und poste sie nicht in Tickets oder Chats. Bei Verdacht legst du in Make einen neuen Webhook an, trägst dessen Adresse im Endpunkt ein und löschst den alten.
Gut zu wissen
- Make antwortet standardmäßig mit
200, wenn die Anfrage angenommen wurde. HocDoc braucht innerhalb von 10 Sekunden ein2xx. Schlägt eine Zustellung fehl, versucht HocDoc es bis zu 8 Mal in etwa einem Tag (Retries). - Ein Webhook, der länger als 5 Tage mit keinem Szenario verbunden ist, wird von Make deaktiviert und antwortet mit
410. Nach 5 endgültig gescheiterten Zustellungen in Folge pausiert HocDoc den Endpunkt. Setze ihn in der Karte Webhooks fort. - Ereignisse können doppelt oder in anderer Reihenfolge kommen. Nutze
iddes Ereignisses, um Doppelte zu erkennen. - Den Verlauf siehst du in der Karte Zustell-Log.
Make → HocDoc: Angebote per API
Hier ruft ein Szenario die HocDoc-API mit dem Modul HTTP > Make a request auf.1
API-Key anlegen
Öffne Einstellungen, Reiter Integrationen, Karte API-Keys, Create API key. Vergib einen Namen wie „Make“. Wähle Read only, wenn das Szenario nur liest, und Read and write, wenn es Angebote anlegt, versendet oder zurückzieht. Kopiere den Key. Er wird nur einmal angezeigt. Mehr dazu: Authentication.
2
Modul hinzufügen
Füge die App HTTP hinzu und wähle die Aktion Make a request.
3
URL, Methode und Header eintragen
Die Basis-URL ist
https://app.hocdoc.com/api/v1. Trage in URL die vollständige Adresse ein, zum Beispiel https://app.hocdoc.com/api/v1/offers, und wähle die Method. Unter Headers fügst du den Header Authorization mit dem Wert Bearer hd_live_... hinzu (dein Key).4
Antwort auslesen
Schalte Parse response ein. Dann stehen die Felder der JSON-Antwort in den nächsten Modulen bereit. Die Daten der Antwort liegen unter
data.401 ist der Key falsch, widerrufen oder abgelaufen. Bei 403 hat der Key nur Leserecht. In den Advanced settings des Moduls steht Return error if HTTP request fails: Schalte es ein, wenn das Szenario bei einem Fehler der API stoppen oder in die Fehlerbehandlung laufen soll.
Angebote lesen
Antworten kommen als
{ "data": ... }. Bei Listen zeigt next_cursor auf die nächste Seite (Pagination).
Angebot anlegen und versenden
Mit einem Key Read and write legt ein Szenario ein Angebot aus einer Vorlage an. Wähle die MethodePOST, die URL https://app.hocdoc.com/api/v1/offers, den Header Authorization wie oben, als Body content type application/json und gib dieses JSON als Body:
template_id und recipient mit name und email sind Pflicht. Alles andere ist optional. Mit variables beantwortest du die Fragen der Vorlage über den Variablennamen. Die Antwort enthält das Angebot als Entwurf mit seiner id.
Zum Versenden nutzt ein zweites Modul POST https://app.hocdoc.com/api/v1/offers/{id}/send mit der id aus dem vorigen Modul. Der Body darf leer sein, mit expires_on (YYYY-MM-DD) setzt du den letzten Annahmetag. Ohne Angabe sind es 14 Tage. Zurückziehen geht mit POST https://app.hocdoc.com/api/v1/offers/{id}/withdraw.
Der Key handelt als die Person, die ihn angelegt hat. Rolle, Freigaben und Tarif gelten wie in der App. Verlangt der Workspace eine Freigabe, versendet die API nicht und antwortet mit 409 und approval_required.
Setzt du Felder aus früheren Modulen in den JSON-Body, achte auf Anführungszeichen und Zeilenumbrüche in den Werten. Sie machen das JSON ungültig. Die Schreibaufrufe sind auf 30 pro Minute je Key begrenzt (Rate limits). Der Header
Idempotency-Key verhindert, dass ein wiederholter Aufruf ein Angebot doppelt anlegt.