Signiertes JSON an Ihren eigenen Endpunkt
Wenn das Ziel Ihr eigenes Backend ist, eine Serverless-Funktion oder ein Tool ohne native Integration, ist ein Webhook die Integration. Jede Einreichung kommt als ein JSON-Ereignis an, nach Feldschlüsseln geordnet, signiert, damit Sie belegen können, dass es von Formstep stammt, und wiederholt, bis Ihr Endpunkt zustimmt.
Aktualisiert
So funktioniert es
- Öffnen Sie die Integrationen des Formulars, wählen Sie Webhook und geben Sie die URL ein. Lassen Sie die Zuordnung leer, um jedes Feld zu senden, oder fügen Sie Zeilen hinzu, um nur einige unter den JSON-Schlüsseln Ihrer Wahl zu senden. See an example request zeigt, wie sich der Body beim Bearbeiten ändert.
- Kopieren Sie das Signing Secret, das mit
whsec_beginnt und nur einmal angezeigt wird. Fügen Sie bis zu fünf eigene Header hinzu, etwa ein Autorisierungs-Token. - Klicken Sie auf Turn on Webhook und dann auf Send a test event: ein signierter POST mit Beispielantworten und Ihren Headern, im Ereignisprotokoll aufgeführt wie eine echte Zustellung.
Was ankommt
Ein Umschlag für alles, was Formstep sendet: id, type, createdAt, apiVersion, test und data. Unter data: das Formular, die Einreichung mit ihrer ID, der E-Mail-Adresse des Antwortenden, Zeit, Sprache und PDF-Link, ein answers-Objekt für Code, nach Feldschlüsseln geordnet, und ein display-Objekt mit denselben Schlüsseln als lesbarer Text. Eine Auswahlantwort ist in answers ihr Optionsschlüssel und in display ihr Label; eine Datei ist eine Liste, im einen mit Download-URLs und im anderen mit Dateinamen. Eine Einreichung, die eine Anfrage beantwortet hat, ergänzt einen request-Block mit Ihrer externen ID und Ihren Metadaten.
X-Formstep-Signature: t=TIMESTAMP,sha256=HEX
Ein Formular kann mehrere Webhooks haben; jeder wird bei jeder Einreichung und jeder späteren Bearbeitung ausgelöst, unterscheidbar am type. Schalten Sie Send the field list with every event ein, wenn Ihr Empfänger fields.list nicht selbst aufrufen kann.
Wiederholungen
Jedes 2xx ist ein Erfolg. Formstep versucht es bis zu fünfmal: sofort, dann nach mindestens 1, 2, 4 und 8 Minuten, sodass der letzte Versuch etwa zwei Stunden nach dem ersten erfolgt. 429, 5xx, Timeouts und Verbindungsfehler werden wiederholt, und ein längeres Retry-After wird beachtet. 401, 403 und 404 stoppen die Integration sofort und schicken der Person, die sie eingerichtet hat, eine E-Mail. Zustellungen, die alle fünf Versuche verbraucht haben, erscheinen in einem Banner an der Integration; Retry all sendet sie erneut und schaltet eine pausierte Integration wieder ein.
Für die lokale Entwicklung machen Sie Ihren Dev-Server mit ngrok oder einem Cloudflare-Tunnel erreichbar und richten den Webhook darauf. Für unfertige Antworten über den öffentlichen Link erstellen Sie mit der REST-API ein submission_abandoned-Abonnement; der Webhook, den Sie hier hinzufügen, wird dafür nie ausgelöst.
Ein Workflow-Tool mit Webhook-Trigger, etwa Make oder Pipedream, kann diese ebenfalls empfangen. Wenn der Empfänger ein Workflow ist, der auf eine bestimmte Person wartet, wollen Sie den Callback einer Anfrage statt eines Webhooks: Er wird einmal ausgelöst, für diese Anfrage, mit ihrem Ergebnis.
