Documentation

[yhrchan]

Is there documentation on how to connect Form SG to external applications using this SDK via webhooks? Where in Form SG to configure for the submissions to point to the external application using this Form SG JavaScript SDK?

[mantariksh]

hi @yhrchan, you can add your webhook URL under the "Settings" tab in your form's admin dashboard. webhooks are only enabled for Storage mode forms, not for email mode.

[yhrchan]

Thanks for the quick response. I am testing this locally on my machine but I don't see a field to fill in the webhook URL under the "Settings" tab in the form dashboard.

[yhrchan]

@mantariksh I see the source code has this field, is there anything special that needs to be configured in order for the webhook url field to show up or to enable this feature?

  <!-- Webhooks for encrypted forms -->
  <div
    ng-if="isFormEncrypt()"
    feature-toggle
    feature-name="webhook-verified-content"
  >
    <div class="row enable-features">
      <label
        for="settings-webhook-url"
        class="col-xs-9 label-custom label-large"
      >
        Webhook Endpoint URL
        <span class="beta-icon"> beta </span>
        <i
          class="glyphicon glyphicon-question-sign"
          uib-tooltip="For developers and IT officers. We will POST encrypted form responses in real-time to the HTTPS endpoint specified here."
          tooltip-trigger="'click mouseenter'"
        ></i>
        <span class="field-optional">(optional)</span>
      </label>
    </div>

[mantariksh]

hi @yhrchan, yes, you need an environment variable called SIGNING_SECRET_KEY in your local environment in order to enable the webhook feature locally. this key is required for the server to be able to sign the webhook POST request. you can take a look at the relevant section of the FormSG docs for more details.

a quick shortcut would be to:

1. grab the secret key from the test portion of the keys in this repo
2. set SIGNING_SECRET_KEY to the secret key you grabbed in step 1 on this line in your FormSG code
3. set FORMSG_SDK_MODE on this line to test instead of development so that the SDK will use the correct public key to verify your local server's signature

please let me know if you face any other issues, or have any suggestions. I'd be happy to help iron out any difficulties in the process. I already opened #68 which will remove the need for these extra steps in future.

[mantariksh]

@yhrchan out of curiosity, can I also check what you're using webhooks for?

[yhrchan]

@mantariksh ah thanks! the webhook url field showed up now so i'll try creating the webhook as a next step. BTW, I am not fluent in Angular so sometimes hard for me to follow the source code. I am only fluent in React but I see in your roadmap that your team is planning to migrate to React, right?

Yes I am building a CRM-like system and see the possibility to integrate FormSG as an intake component and within the CRM different workflows could be configured for downstream functionalities. Just curious, would there be a possibility to meet online to have some overview of FormSG from your perspective? I am sure I have some questions to ask in terms of future Roadmap and architecture.

Thanks for your help! =)

[yhrchan]

@mantariksh I've tried putting in an address in the webhook url field such as http://localhost:3003 but the field validation won't let me. Is there any way to test the webhook where the webhook resides locally without HTTPS?

[yhrchan]

@mantariksh so I was able to use ngrok to expose my local server publicly via a HTTPS address and seems like FormSG could establish connection to my local webhook. However, some config might not be right as I am getting a 401 Unauthorized response.

webhook source code
const POST_URI =https://address.ngrok.io/submissions

Webhook Endpoint URL
https://address.ngrok.io/submissions

Also in the webhook code, i've entered in the form secret key in the following line:
const formSecretKey = xxxxxxxxxxxxxxxxxxxxxx

HTTP Requests

POST /submissions 401 Unauthorized

[yhrchan]

@mantariksh

Ok got it to work!

Have to use set mode = test so that it uses the same public key in the webhook code

const formsg = require('@opengovsg/formsg-sdk')({
mode: 'test',
})

[mantariksh]

hey @yhrchan, sorry for the late response, we've been caught up with reviews on the main FormSG repo.

yes, we are planning to start the migration to React in the next couple of weeks actually. you can see the issues we've scoped out here.

sure, happy to meet online! I'm curious about your use case as well. feel free to drop me an email at [email protected] and we can set it up.

[mantariksh]

@yhrchan we also introduced retries for webhooks in the main repo, if that's useful for you