Platforms
Embedding in a Flutter App
Embed the signing ceremony in a Flutter app with webview_flutter, catch its result from the navigation delegate and confirm the outcome on your server.
Your Flutter app shows the signing ceremony in a webview_flutter WebViewWidget and learns how it ended without leaving the app. The same code runs on iOS and Android.
The code is written for Flutter 3 and webview_flutter 4.
How it works
- Your server creates the envelope with custom authentication. SignatureAPI returns the ceremony URL to your server instead of emailing it. Your server passes the URL to the app.
- The app appends
embedded=true&event_delivery=redirectto the URL and loads it as the WebView’s page. - When the ceremony ends, it navigates to a
signatureapi-message://URL. The WebView’sonNavigationRequestcallback cancels that navigation and reads the event from the URL. - The app asks your server whether the recipient really signed before it shows a result.
The ceremony is the WebView’s top-level page, so the recipient’s ceremony needs no embeddable_in.
Create the ceremony on your server
Create the envelope on your server and give the signer a ceremony with custom authentication:
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement",
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "signer"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "signer",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"ceremony": {
"authentication": [
{
"type": "custom",
"provider": "Acme Portal",
"data": {
"user_id": "usr_12345"
}
}
],
"redirect_delay": 0
}
}
]
}customauthentication makes SignatureAPI return the ceremony URL instead of emailing it. Put references to your own login session indata; they appear in the audit log.redirect_delay: 0is optional. It hands control back to the app as soon as the signer finishes, so the app can show its own result screen. Without it, the ceremony shows its own result page for 3 seconds.- Leave out
redirect_urlandembeddable_in. Embedded ceremonies ignore the first, and a top-level WebView doesn’t need the second.
The 201 Created response already contains the signer’s ceremony URL in recipients[].ceremony.url. The envelope starts in processing, and the ceremony opens only once the envelope is in_progress; before that, it asks the signer to try again later. Return the URL to the app after the envelope.started webhook, or after reading the envelope with GET /v1/envelopes/{id} and seeing in_progress.
The ceremony URL lets whoever holds it sign as the recipient. Don’t log it and don’t store it on the device. To resume later, ask your server for the current URL.
Add the package
flutter pub add webview_flutterOn Android, the release build needs the internet permission. Flutter’s template adds it only to the debug and profile manifests, so add it to android/app/src/main/AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET" />Read the event from the URL
With event_delivery=redirect, the ceremony ends by navigating to a signatureapi-message:// URL:
- The URL’s host is the event type, such as
ceremony.completed. - On
ceremony.failed, the query carrieserror_typeanderror_message, form-encoded (+is a space).
signatureapi-message://ceremony.failed/?error_type=unauthorized&error_message=The+link+is+no+longer+valid.CeremonyEvent parses that URL, and embeddedCeremonyUrl adds the two query parameters to the URL from your server. Dart’s Uri decodes + as a space in queryParameters:
/// A terminal event from an embedded ceremony.
///
/// With `event_delivery=redirect` the ceremony reports how it ended by
/// navigating to `signatureapi-message://<type>/?error_type=...&error_message=...`.
/// Branch on [type] and [errorType] only: [errorMessage] is for logs.
class CeremonyEvent {
const CeremonyEvent({required this.type, this.errorType, this.errorMessage});
static const scheme = 'signatureapi-message';
final String type;
final String? errorType;
final String? errorMessage;
bool get isCompleted => type == 'ceremony.completed';
/// Returns the event a `signatureapi-message://` URL describes, or null for any other URL.
static CeremonyEvent? fromUri(Uri uri) {
if (uri.scheme != scheme || uri.host.isEmpty) return null;
return CeremonyEvent(
type: uri.host,
errorType: uri.queryParameters['error_type'],
errorMessage: uri.queryParameters['error_message'],
);
}
}
/// Adds `embedded=true` and `event_delivery=redirect` to the ceremony URL from your server.
Uri embeddedCeremonyUrl(String ceremonyUrl) {
final uri = Uri.parse(ceremonyUrl);
return uri.replace(queryParameters: {
...uri.queryParameters,
'embedded': 'true',
'event_delivery': 'redirect',
});
}Show the ceremony
CeremonyScreen loads the ceremony as the WebView’s page. Its navigation delegate lets every ceremony page load, and stops the signatureapi-message:// navigation to pass the event to onEvent:
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'ceremony_event.dart';
class CeremonyScreen extends StatefulWidget {
const CeremonyScreen({super.key, required this.ceremonyUrl, required this.onEvent});
final String ceremonyUrl;
final void Function(CeremonyEvent event) onEvent;
@override
State<CeremonyScreen> createState() => _CeremonyScreenState();
}
class _CeremonyScreenState extends State<CeremonyScreen> {
late final WebViewController _controller;
bool _ended = false;
@override
void initState() {
super.initState();
_controller = WebViewController()
// The ceremony needs JavaScript.
..setJavaScriptMode(JavaScriptMode.unrestricted)
..setNavigationDelegate(NavigationDelegate(onNavigationRequest: _onNavigationRequest))
..loadRequest(embeddedCeremonyUrl(widget.ceremonyUrl));
}
NavigationDecision _onNavigationRequest(NavigationRequest request) {
final event = CeremonyEvent.fromUri(Uri.parse(request.url));
if (event == null) return NavigationDecision.navigate;
if (!_ended) {
_ended = true;
widget.onEvent(event);
}
// Cancel the navigation: there is no page at signatureapi-message://.
return NavigationDecision.prevent;
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Sign document')),
body: SafeArea(child: WebViewWidget(controller: _controller)),
);
}
}This is a client-side navigation, not an HTTP redirect. No request reaches the network, so only the navigation delegate sees it.
To hide the ceremony’s own Cancel control, for example because your app bar has its own back button, also add 'allow_cancel': 'false' to the query parameters. See Disable Cancel.
Handle each outcome
Close the screen, then branch on the event type, and on errorType for failures. Confirm a completed ceremony on your server before you show success:
Navigator.of(context).push(MaterialPageRoute(
builder: (_) => CeremonyScreen(
ceremonyUrl: ceremonyUrl,
onEvent: (event) async {
Navigator.of(context).pop();
switch (event.type) {
case 'ceremony.completed':
// The event comes from the device: ask your server, which reads the envelope.
final signed = await api.hasSigned(envelopeId);
showResult(signed ? 'Document signed' : 'Still processing your signature');
case 'ceremony.canceled':
break; // The signer chose Cancel: stay on the previous screen.
case 'ceremony.declined':
showResult('Document declined');
case 'ceremony.failed':
debugPrint('Ceremony failed: ${event.errorType} ${event.errorMessage}');
showResult('This signing link no longer works. Try again.');
}
},
),
));api.hasSigned and showResult stand for your own server call and UI. On your server, read the envelope with GET /v1/envelopes/{id} and check that the recipient’s status is completed, or use the recipient.completed webhook. See Event types for every event and Error types for the error_type values.
Test the integration
Use a test API key: test envelopes are free and not legally binding. Open the ceremony, sign the sample document and select Finish. The screen closes and your app shows the result.
The ceremony only completes after input a person produces, such as a touch. In integration tests, drive the WebView with real gestures; see Automated testing.
Keep learning
- Ceremony Events: every event, its payload and when it arrives.
- Ceremony Customization: accent color, Cancel button and result page delay.
- iOS and Android: native guides with the same flow, including message delivery.