- HocDoc → Zapier: Ein Webhook von HocDoc startet einen Zap, zum Beispiel wenn ein Angebot angenommen wird.
- Zapier → HocDoc: Ein Zap ruft die API von HocDoc mit einem API-Key auf, um Angebote zu lesen, anzulegen, zu versenden oder zurückzuziehen.
Nur Inhaber und Admins legen Webhooks und API-Keys an. Mehr dazu unter Einstellungen und Team und Rollen. Brauchst du nur Nachrichten in Slack oder Teams, geht das ohne Zapier: Benachrichtigungen und Verbindungen.
HocDoc → Zapier: ein Zap startet bei einem Ereignis
1
Trigger in Zapier anlegen
Lege einen neuen Zap an. Wähle als Trigger die App Webhooks by Zapier und als Event Catch Hook. Wähle Continue. Pick Off A Child Key lässt du leer.
2
Webhook-Adresse kopieren
Im Tab Test zeigt Zapier die Webhook-Adresse. Kopiere sie.
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 Zapier-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. Gehe in Zapier zurück in den Tab Test und wähle Test trigger. Zapier zeigt die Felder des Ereignisses.5
Mit echten Daten testen
Ein
ping hat keine Angebotsdaten (data ist leer). Löse darum ein echtes Ereignis aus, zum Beispiel indem du ein Testangebot annimmst, und wähle in Zapier noch einmal Test trigger. Dann findest du Felder wie data.offer.title oder data.offer.recipient.email für die nächsten Schritte.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: Angebot angenommen
Der Zap hat zwei Schritte: Webhooks by Zapier (Catch Hook) als Trigger, danach eine Aktion. Filtere im Zap auftype gleich offer.accepted, wenn der Endpunkt mehrere Ereignisse bekommt.
Die genauen Namen der Events und Felder in diesen Apps legt Zapier fest. Wenn dein CRM eine eigene Verbindung in HocDoc hat, brauchst du Zapier dafür nicht (Reiter Integrationen, Karte Verbindungen).
Sicherheit: Signatur und Adresse
HocDoc signiert jede Anfrage nach Standard Webhooks mit den Headernwebhook-id, webhook-timestamp und webhook-signature. Der Trigger Catch Hook von Zapier ist dafür nicht gedacht. Er prüft die Signatur nicht. Zapier bietet daneben Catch Raw Hook an, das unverarbeitete Daten und Header liefert. Eine Prüfung der Signatur in einem eigenen Code-Schritt beschreibt diese Anleitung nicht. Das Prüfverfahren 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, poste sie nicht in Tickets oder Chats und lege bei Verdacht einen neuen Trigger an, trage dessen Adresse im Endpunkt ein und lösche den alten Zap.
Gut zu wissen
- Zapier muss innerhalb von 10 Sekunden mit einem
2xxantworten. Schlägt eine Zustellung fehl, versucht HocDoc es bis zu 8 Mal in etwa einem Tag (Retries). - Nach 5 endgültig gescheiterten Zustellungen in Folge pausiert HocDoc den Endpunkt. Setze ihn in der Karte Webhooks fort. Ereignisse während der Pause kommen nicht nach.
- 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.
Zapier → HocDoc: Angebote per API
Hier ruft ein Zap die HocDoc-API auf. Du brauchst einen API-Key.1
API-Key anlegen
Öffne Einstellungen, Reiter Integrationen, Karte API-Keys, Create API key. Vergib einen Namen wie „Zapier“. Wähle Read only, wenn der Zap nur liest, und Read and write, wenn er Angebote anlegt, versendet oder zurückzieht. Kopiere den Key. Er wird nur einmal angezeigt. Mehr dazu: Authentication.
2
Aktion in Zapier wählen
Füge als Aktion Webhooks by Zapier hinzu. Als Event wählst du GET zum Lesen oder Custom Request für Aufrufe mit JSON-Body.
3
URL 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. Im Abschnitt Headers legst du den Header Authorization mit dem Wert Bearer hd_live_... an (dein Key).4
Testen
Teste den Schritt. Bei Erfolg zeigt Zapier die Antwort. Bei
401 ist der Key falsch, widerrufen oder abgelaufen. Bei 403 hat der Key nur Leserecht.Authorization.
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 Zap ein Angebot aus einer Vorlage an. Wähle Custom Request, Methode POST, URLhttps://app.hocdoc.com/api/v1/offers, den Header Authorization wie oben und den Header Content-Type mit dem Wert application/json. Ins Feld Data kommt das JSON:
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 ruft ein zweiter Schritt POST https://app.hocdoc.com/api/v1/offers/{id}/send auf, mit der id aus dem vorigen Schritt. 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.
Zapier gibt Felder aus früheren Schritten als Text in den Body. Ein Wert mit Anführungszeichen oder Zeilenumbruch macht das JSON ungültig. Die API antwortet dann mit einem Fehler. 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.