How to integrate e-signatures into a Go application

An e-signature integration lets your Go service own the full signing loop instead of sending people out to another product. That keeps the workflow inside the app your users already know, and it removes the extra tabs and handoffs that usually slow the document signing process down.

In this blog post, we'll show you how to easily add e-signing into your own application using Formable. Formable offers a robust Go SDK and detailed documentation to make the integration process as easy as possible.

What you'll need:

• Go 1.22 or newer
• A Formable account (paid or free sandbox)
• An API key from Formable account settings

---

Table of Contents

• Why an e-signature API from Go?
• Step 1: installing the Formable Go SDK
• Step 2: creating the client
• Step 3: create a template from your document
• Step 4: choose a signing flow
• Step 5: embed signing in a Go HTTP server
• Step 6: handle webhooks
• Step 7: download the signed PDF
• Error handling and test mode
• Conclusion
• FAQs

Why an e-signature API from Go?

Say you write Go for a brokerage platform. Each deal still needs listing agreements, purchase contracts, and addenda signed by agents, buyers, and sellers. When that lives in email attachments and a shared drive, the latest file goes missing, nobody can tell who has signed, and closing slips. By integrating with Formable, all those manual signing processes can be automated within the brokerage.

---

Step 1: installing the Formable Go SDK

go get github.com/FormableDocs/formable-go

Note:
For more details and advanced usage, you can also reference the Official Formable Go SDK Documentation.

---

Step 2: creating the client

Create a Formable API client using the sdk.

package main

import (
    "log"
    "os"

    "github.com/FormableDocs/formable-go"
)

func main() {
    client, err := formable.NewClient(os.Getenv("FORMABLE_API_KEY"))
    if err != nil {
        log.Fatal(err)
    }
    _ = client
}

---

Step 3: create a template from your document

A template is the re-usable document where you or your users place the fields for the signers to fill in.

Signer roles are optional for single signers. If you need to support multi-party signing, they are required as you need to specify which role needs to fill out which field.

created, err := client.Templates.CreateFromFile(
    ctx,
    "sow.pdf",
    []formable.TemplateSignerRole{
        {Name: "Contractor", Order: 0},
        {Name: "HiringManager", Order: 1},
    },
)
if err != nil {
    return err
}

templateID := created.TemplateID
log.Println(created.EditTemplateAccess.EditURL)

Open the edit URL, place at least one required signature field, assign it Contractor. The URL expires after a day:

edit, err := client.Templates.CreateEditURL(ctx, templateID)
if err != nil {
    return err
}
log.Println(edit.EditURL)

Save templateID and reuse it for later signature requests.

---

Step 4: choose a signing flow

You can choose to send a signing link via email to your user, or have your user sign within your own application within an iFrame.

If choosing email delivery, implement using the following code snippet.

request, err := client.SignatureRequests.Create(ctx, &formable.CreateSignatureRequest{
    TemplateID: templateID,
    Signers: []formable.Signer{
        {Email: "jane@example.com", Name: "Jane Doe", Role: "Contractor"},
        {Email: "mgr@yourco.com", Name: "Alex Chen", Role: "HiringManager"},
    },
    TestMode: true,
})
if err != nil {
    return err
}

log.Println(request.SignatureRequestID) // save this

If you want your users to sign inside your application, the next section will show you how to implement the iframe path.

---

Step 5: embed signing in your go application

Embedded signing requires two server calls.

First: Create the signature request.

Second: Mint a short-lived signing URL using the id from the signature request.

mux := http.NewServeMux()

mux.HandleFunc("POST /api/signature-requests", func(w http.ResponseWriter, r *http.Request) {
    var body struct {
        TemplateID string `json:"templateId"`
        Signer     struct {
            Email string `json:"email"`
            Name  string `json:"name"`
        } `json:"signer"`
    }
    if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    request, err := client.SignatureRequests.CreateEmbedded(r.Context(), &formable.CreateSignatureRequest{
        TemplateID: body.TemplateID,
        Signers:    []formable.Signer{{Email: body.Signer.Email, Name: body.Signer.Name, Role: "Contractor"}},
        TestMode:   true,
    })
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadGateway)
        return
    }

    json.NewEncoder(w).Encode(map[string]string{
        "signatureRequestId":   request.SignatureRequestID,
        "recipientSignatureId": request.Signers[0].RecipientSignatureID,
    })
})

mux.HandleFunc("GET /api/signing-url", func(w http.ResponseWriter, r *http.Request) {
    signing, err := client.SignatureRequests.CreateSigningURL(
        r.Context(),
        r.URL.Query().Get("recipientSignatureId"),
    )
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadGateway)
        return
    }
    json.NewEncoder(w).Encode(map[string]string{
        "signingUrl": signing.SigningURL,
        "expiresAt":  signing.ExpiresAt,
    })
})

On the client, fetch the URL from your Go service and load it in an iframe. Formable posts onSigningComplete to the parent window:

const { signingUrl } = await fetch(
  `/api/signing-url?recipientSignatureId=${recipientSignatureId}`
).then((res) => res.json());

document.getElementById("signing-frame").src = signingUrl;

window.addEventListener("message", (event) => {
  if (event.origin !== "https://app.formabledocs.com") return;
  if (event.data?.type === "onSigningComplete") {
    // close the iframe or show a success state
  }
});

<iframe
  id="signing-frame"
  width="100%"
  height="800"
  allow="fullscreen"
  style="border: none;"
></iframe>

***

Step 6: handle webhooks

Register the path in Settings and keep the secret. Read the body with io.ReadAll before you unmarshal. Hashing a re-encoded JSON object will fail verification. On Chi or Gin, use c.GetRawData() / io.ReadAll(c.Request.Body) the same way. Do not call c.BindJSON first.

mux.HandleFunc("POST /webhooks/formable", func(w http.ResponseWriter, r *http.Request) {
    secret, err := base64.StdEncoding.DecodeString(os.Getenv("FORMABLE_WEBHOOK_SECRET"))
    if err != nil {
        http.Error(w, "invalid secret", http.StatusInternalServerError)
        return
    }

    rawBody, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "invalid body", http.StatusBadRequest)
        return
    }

    mac := hmac.New(sha256.New, secret)
    mac.Write(rawBody)
    expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
    received := r.Header.Get("Content-Sha256")
    if !hmac.Equal([]byte(expected), []byte(received)) {
        http.Error(w, "invalid signature", http.StatusUnauthorized)
        return
    }

    var payload struct {
        Event struct {
            EventType string `json:"event_type"`
        } `json:"event"`
        Signing struct {
            SignatureRequestID string `json:"signature_request_id"`
        } `json:"signing"`
    }
    if err := json.Unmarshal(rawBody, &payload); err != nil {
        http.Error(w, "invalid json", http.StatusBadRequest)
        return
    }

    if payload.Event.EventType == "document_completed" {
        envelope, err := client.SignatureRequests.GetSignedEnvelope(
            r.Context(),
            payload.Signing.SignatureRequestID,
        )
        if err != nil {
            http.Error(w, err.Error(), http.StatusBadGateway)
            return
        }
        _ = envelope.SignedEnvelopePresignedURL
        // download, store the PDF, mark the record complete
    }

    w.WriteHeader(http.StatusOK)
})

document_completed is the terminal event. Once you receive this event, this means all parties have signed the document, and you may now fetch the signed document.

Alternatively, if you don't want to expose a webhook endpoint, you can poll for signature request status updates.

current, err := client.SignatureRequests.Get(ctx, signatureRequestID)
if err != nil {
    return err
}
if current.Status == formable.SignatureRequestStatusCompleted {
    // safe to download
}

recent, err := client.SignatureRequests.List(ctx, &formable.ListOptions{
    UpdatedSince: time.Now().UTC().Add(-24 * time.Hour),
})
_ = recent

---

Step 7: download the signed PDF

The signed envelope URL is a short-lived presigned link.

envelope, err := client.SignatureRequests.GetSignedEnvelope(ctx, signatureRequestID)
if err != nil {
    return err
}

resp, err := http.Get(envelope.SignedEnvelopePresignedURL)
if err != nil {
    return err
}
defer resp.Body.Close()
pdf, err := io.ReadAll(resp.Body)

The signed envelope includes the Formable audit trail of all relevant events.

---

Error handling and test mode

Non-2xx responses return a *formable.Error. A 409 from GetSignedEnvelope means the document is not finished:

_, err := client.SignatureRequests.GetSignedEnvelope(ctx, signatureRequestID)
var apiErr *formable.Error
if errors.As(err, &apiErr) && apiErr.Status == 409 {
    // wait for document_completed
    return nil
}

400 is usually a FieldID that is not on the template. 401 is the API key. 404 is an unknown id.

Set TestMode: true while you integrate. Test documents are watermarked, not legally binding, and do not count toward billing. Clear the flag for production.

---

Conclusion

Your Go service now owns signing end to end: a reusable template, email or embedded signing, a verified webhook, and a signed PDF with an audit trail stored on your side. The same handlers work whether the document is finance, HR, real estate, or anything else your app already creates.

To learn more about the Formable API, take a look at our API documentation. We support SDKs for a wide variety of languages, and are always looking to support more in the near future.

If you have questions, email matt@formabledocs.com. We are always happy to assist you!

---

FAQs

How do I add e-signatures to a Go application?

Install formable-go, create a template from your PDF or DOCX, then create a signature request. Formable can email signers, or you can generate a signing URL and embed it in an iframe. A webhook tells you when to download the signed PDF.

Does the SDK depend on a web framework?

No. It uses net/http. The examples use ServeMux. Chi, Echo, and Gin work the same way: read the raw body on the webhook route, and pass c.Request().Context() (or equivalent) into SDK calls.

How do I know when a document has been signed?

Handle document_completed on your webhook, or poll Get until Status is Completed.

Can I test without sending legally binding documents?

Yes. Set TestMode: true on signature requests. Test documents are watermarked, not legally binding, and do not count toward billing.

Does the signed PDF include an audit trail?

Yes. Every signed document includes an appended audit trail with created, sent, signed, and completed events, including timestamps, actors, and IP addresses, which supports enforceability under ESIGN and UETA.