Skip to main content

formsg Adaptor developer README.md

Source: https://github.com/OpenFn/adaptors/tree/main/packages/formsg

language-formsg

An OpenFn adaptor for decrypting and verifying FormSG webhook submissions.

Overview​

This adaptor wraps the @opengovsg/formsg-sdk to provide easy decryption and verification of FormSG form submissions in OpenFn workflows.

Key Features:

  • Decrypt end-to-end encrypted FormSG submissions
  • Verify webhook signatures (for official FormSG deployments)
  • Support for multiple FormSG environments (production, staging, development)

Documentation​

View the docs site for full technical documentation.

Configuration​

View the configuration-schema for required and optional configuration properties.

Sample configuration:

{
  "formSecretKey": "your-form-secret-key-from-formsg",
  "mode": "development",
  "webhookEndpoint": "https://your-domain.com/webhook"
}

Usage Examples​

Decrypt a submission (without signature verification)​

decryptSubmission(state.data);

Decrypt with signature verification​

decryptSubmission(state.data, {
  verifySignature: true,
  signatureHeader: state.headers['x-formsg-signature']
});

Process webhook (verify and decrypt in one step)​

processWebhook(state.data, state.headers['x-formsg-signature']);

Important Limitations​

Webhook Signature Verification​

The FormSG SDK uses hardcoded public signing keys for webhook signature verification. This means:

✅ Signature verification works with:

  • Official FormSG production
  • Official FormSG staging
  • FormSG deployed in development mode
  • FormSG deployed in test mode

❌ Signature verification does NOT work with:

  • Custom FormSG deployments using different signing keys

Why This Limitation Exists​

The signing keys in the SDK (see signing-keys.ts) are used to verify that webhooks genuinely come from official FormSG servers. Custom deployments use different signing keys that aren't in the SDK.

Decryption Always Works​

Form submission decryption works with ANY FormSG deployment (official or custom), as long as you have the form's secret key. The limitation only applies to webhook signature verification.

Workarounds for Custom Deployments​

If you're running a custom FormSG deployment:

  1. Use development/test mode - Deploy your FormSG instance using the public development or test signing keys from the SDK
  2. Skip signature verification - Use decryptSubmission() without the verifySignature option
  3. Fork the SDK - Modify the SDK to inject your custom public signing key (or contribute back via PR!)

Development​

Clone the adaptors monorepo. Follow the "Getting Started" guide inside to get set up.

Run tests using pnpm run test or pnpm run test:watch

Build the project using pnpm build.

To build only the docs run pnpm build docs.

Testing Locally​

See LOCAL_TEST.md for instructions on testing this adaptor locally with the OpenFn CLI.

Resources​