Add E-Signatures to Go (Golang) Applications via REST API (2026)

package signbee

import "time"

// SendDocumentRequest defines the parameters required to dispatch a contract.
type SendDocumentRequest struct {
	Markdown       string `json:"markdown"`
	RecipientName  string `json:"recipient_name"`
	RecipientEmail string `json:"recipient_email"`
	ExpirationDays int    `json:"expiration_days,omitempty"`
}

// SendDocumentResponse defines the structured response returned by Signbee.
type SendDocumentResponse struct {
	DocumentID string `json:"document_id"`
	SigningURL string `json:"signing_url"`
	Status     string `json:"status"`
	CreatedAt  string `json:"created_at"`
}

// APIErrorResponse represents an error payload returned by non-2xx responses.
type APIErrorResponse struct {
	Error   string `json:"error"`
	Message string `json:"message"`
	Code    int    `json:"code,omitempty"`
}

// WebhookEvent represents an incoming real-time signature event.
type WebhookEvent struct {
	Event     string       `json:"event"`
	Timestamp string       `json:"timestamp"`
	Data      EventPayload `json:"data"`
}

// EventPayload contains details regarding document updates.
type EventPayload struct {
	DocumentID   string `json:"document_id"`
	SignerName   string `json:"signer_name"`
	SignerEmail  string `json:"signer_email"`
	SignedPDFURL string `json:"signed_pdf_url,omitempty"`
}

package signbee

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"
)

// Client wraps HTTP operations for the Signbee REST API.
type Client struct {
	APIKey     string
	BaseURL    string
	HTTPClient *http.Client
}

// NewClient returns a configured Signbee API client instance.
func NewClient(apiKey string) *Client {
	return &Client{
		APIKey:  apiKey,
		BaseURL: "https://signb.ee/api/v1",
		HTTPClient: &http.Client{
			Timeout: 30 * time.Second,
		},
	}
}

// SendDocument dispatches a Markdown document for e-signature.
func (c *Client) SendDocument(ctx context.Context, req SendDocumentRequest) (*SendDocumentResponse, error) {
	jsonBytes, err := json.Marshal(req)
	if err != nil {
		return nil, fmt.Errorf("signbee: failed to marshal request: %w", err)
	}

	httpReq, err := http.NewRequestWithContext(
		ctx,
		http.MethodPost,
		c.BaseURL+"/send",
		bytes.NewReader(jsonBytes),
	)
	if err != nil {
		return nil, fmt.Errorf("signbee: failed to construct request: %w", err)
	}

	httpReq.Header.Set("Content-Type", "application/json")
	httpReq.Header.Set("Authorization", "Bearer "+c.APIKey)

	resp, err := c.HTTPClient.Do(httpReq)
	if err != nil {
		return nil, fmt.Errorf("signbee: network request failed: %w", err)
	}
	defer resp.Body.Close()

	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("signbee: failed to read response body: %w", err)
	}

	// Handle Rate Limiting (HTTP 429)
	if resp.StatusCode == http.StatusTooManyRequests {
		retryAfter := resp.Header.Get("Retry-After")
		return nil, fmt.Errorf("signbee: rate limited (429), retry after %s seconds: %s", retryAfter, string(respBody))
	}

	// Handle Non-2xx Status Codes
	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
		var apiErr APIErrorResponse
		if err := json.Unmarshal(respBody, &apiErr); err == nil && apiErr.Message != "" {
			return nil, fmt.Errorf("signbee API error (%d): %s", resp.StatusCode, apiErr.Message)
		}
		return nil, fmt.Errorf("signbee API returned status %d: %s", resp.StatusCode, string(respBody))
	}

	var result SendDocumentResponse
	if err := json.Unmarshal(respBody, &result); err != nil {
		return nil, fmt.Errorf("signbee: failed to decode success payload: %w", err)
	}

	return &result, nil
}

package signbee

import (
	"crypto/hmac"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/hex"
	"encoding/json"
	"io"
	"net/http"
)

// VerifyWebhookSignature checks if headerSig matches HMAC-SHA256 of payload.
func VerifyWebhookSignature(payload []byte, headerSig string, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(payload)
	expectedSig := hex.EncodeToString(mac.Sum(nil))

	if len(headerSig) != len(expectedSig) {
		return false
	}
	return subtle.ConstantTimeCompare([]byte(headerSig), []byte(expectedSig)) == 1
}

// HTTPWebhookHandler constructs an http.HandlerFunc for standard net/http servers.
func HTTPWebhookHandler(webhookSecret string) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if r.Method != http.MethodPost {
			http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
			return
		}

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

		signatureHeader := r.Header.Get("X-Signbee-Signature")
		if !VerifyWebhookSignature(body, signatureHeader, webhookSecret) {
			http.Error(w, "Invalid HMAC signature", http.StatusUnauthorized)
			return
		}

		var event WebhookEvent
		if err := json.Unmarshal(body, &event); err != nil {
			http.Error(w, "Invalid JSON payload", http.StatusBadRequest)
			return
		}

		switch event.Event {
		case "document.signed":
			// Trigger application logic for signed agreement
			w.WriteHeader(http.StatusOK)
			w.Write([]byte(`{"status":"processed"}`))
		case "document.viewed":
			// Track recipient activity
			w.WriteHeader(http.StatusOK)
		default:
			w.WriteHeader(http.StatusOK)
		}
	}
}

package main

import (
	"io"
	"net/http"

	"github.com/gin-gonic/gin"
	"yourproject/signbee"
)

func RegisterGinWebhookRoute(router *gin.Engine, secret string) {
	router.POST("/webhooks/signbee", func(c *gin.Context) {
		body, err := io.ReadAll(c.Request.Body)
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": "Cannot read request body"})
			return
		}

		signature := c.GetHeader("X-Signbee-Signature")
		if !signbee.VerifyWebhookSignature(body, signature, secret) {
			c.JSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized signature"})
			return
		}

		var event signbee.WebhookEvent
		if err := json.Unmarshal(body, &event); err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": "Malformed JSON payload"})
			return
		}

		if event.Event == "document.signed" {
			// Update local state or notify user
		}

		c.JSON(http.StatusOK, gin.H{"status": "received"})
	})
}

package db

import (
	"context"
	"fmt"
	"time"

	"gorm.io/gorm"
)

// DocumentRecord represents the persistent state of an e-signature request.
type DocumentRecord struct {
	ID            uint      `gorm:"primaryKey"`
	DocumentID    string    `gorm:"uniqueIndex;not null"`
	RecipientName string    `gorm:"not null"`
	RecipientEmail string   `gorm:"not null"`
	Status        string    `gorm:"index;not null;default:'pending'"`
	SigningURL    string    `gorm:"not null"`
	SignedPDFURL  string    `gorm:"default:''"`
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

type GORMStore struct {
	db *gorm.DB
}

func NewGORMStore(db *gorm.DB) *GORMStore {
	return &GORMStore{db: db}
}

// CreateDocument inserts a new signature record upon dispatch.
func (s *GORMStore) CreateDocument(ctx context.Context, doc *DocumentRecord) error {
	if err := s.db.WithContext(ctx).Create(doc).Error; err != nil {
		return fmt.Errorf("gorm: failed to save document record: %w", err)
	}
	return nil
}

// UpdateDocumentStatus updates status and PDF URL upon receiving webhooks.
func (s *GORMStore) UpdateDocumentStatus(ctx context.Context, docID string, status string, pdfURL string) error {
	err := s.db.WithContext(ctx).Model(&DocumentRecord{}).
		Where("document_id = ?", docID).
		Updates(map[string]interface{}{
			"status":         status,
			"signed_pdf_url": pdfURL,
			"updated_at":     time.Now(),
		}).Error

	if err != nil {
		return fmt.Errorf("gorm: failed to update document status: %w", err)
	}
	return nil
}

package db

import (
	"context"
	"database/sql"
	"fmt"
	"time"
)

type SQLStore struct {
	db *sql.DB
}

func NewSQLStore(db *sql.DB) *SQLStore {
	return &SQLStore{db: db}
}

func (s *SQLStore) UpdateStatus(ctx context.Context, docID, status, pdfURL string) error {
	query := `
		UPDATE document_records
		SET status = $1, signed_pdf_url = $2, updated_at = $3
		WHERE document_id = $4
	`
	result, err := s.db.ExecContext(ctx, query, status, pdfURL, time.Now(), docID)
	if err != nil {
		return fmt.Errorf("sql: failed executing update query: %w", err)
	}

	rows, err := result.RowsAffected()
	if err != nil {
		return err
	}
	if rows == 0 {
		return fmt.Errorf("sql: no document record found with ID %s", docID)
	}

	return nil
}