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

• FormSG JavaScript SDK
• FormSG Documentation
• FormSG Self-hosting Documentation
• OpenFn Documentation