Formstep

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

  1. Ö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.
  2. 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.
  3. 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.

Ganzen Guide ansehen

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.

Fragen zu Formstep für Webhooks

Noch etwas auf dem Herzen? Die Dokumentation behandelt jede Einstellung, und wir antworten auf E-Mails.

Dokumentation lesen

Ein Webhook gehört zum Formular und wird bei jeder Einreichung ausgelöst, über Freigabelinks und Anfragen gleichermaßen. Ein Callback gehört zu einer Anfrage: die URL, die Sie beim Erstellen als callbackUrl übergeben und die einmal aufgerufen wird, wenn die Anfrage endet. Beide tragen denselben Ereignis-Umschlag.

Jede Anfrage hat einen Header X-Formstep-Signature der Form t=TIMESTAMP,sha256=HEX: ein HMAC-SHA256 aus TIMESTAMP, einem Punkt und dem rohen Body, mit Ihrem Signing Secret. Hashen Sie den Body genau so, wie er ankam. Die Webhook-Referenz enthält ein Snippet zum Kopieren.

Der Inhaber des Arbeitsbereichs kann es im Dashboard anzeigen; andere Mitglieder sehen den Rest des Webhooks. Es lässt sich nicht neu erzeugen: Für ein neues Secret löschen Sie den Webhook und erstellen einen neuen.

HTTPS auf einer öffentlichen Adresse, bis zu 2.048 Zeichen, ohne Zugangsdaten in der URL. Reines http:// funktioniert für localhost während der Entwicklung. Formstep prüft den Hostnamen vor jeder Zustellung erneut, sodass ein DNS-Eintrag, der später auf eine interne Adresse zeigt, trotzdem abgelehnt wird.

Holen Sie Informationen von jedem ein.

Veröffentlichen Sie ein Beispielformular, füllen Sie es aus wie Ihr Empfänger und sehen Sie, wie die Antworten zurückkommen. Kein Konto nötig.

Dokumentation lesen