Salesforce Apex E-Signature Integration: REST Callouts & Webhooks (2026)

public with sharing class SignbeeService {
    public class SignbeeApiException extends Exception {}

    // Request wrapper matching Signbee API contract
    public class SendDocumentRequest {
        public String markdown;
        public String recipient_name;
        public String recipient_email;
        public String title;
        public String redirect_url;
        public String webhook_url;
        public Map<String, String> metadata;
    }

    // Response wrapper
    public class SendDocumentResponse {
        public String document_id;
        public String signing_url;
        public String status;
        public String error;
    }

    // Invocable Action input for Salesforce Flow Builder
    public class FlowInput {
        @InvocableVariable(label='Opportunity ID' required=true)
        public Id opportunityId;

        @InvocableVariable(label='Recipient Name' required=true)
        public String recipientName;

        @InvocableVariable(label='Recipient Email' required=true)
        public String recipientEmail;

        @InvocableVariable(label='Document Title' required=false)
        public String documentTitle;
    }

    // Invocable Action output for Salesforce Flow Builder
    public class FlowOutput {
        @InvocableVariable(label='Document ID')
        public String documentId;

        @InvocableVariable(label='Signing URL')
        public String signingUrl;

        @InvocableVariable(label='Success')
        public Boolean isSuccess;

        @InvocableVariable(label='Error Message')
        public String errorMessage;
    }

    /**
     * Invocable method callable from Salesforce Flow
     */
    @InvocableMethod(label='Send E-Signature via Signbee' description='Sends contract for electronic signature using Signbee API' category='E-Signature')
    public static List<FlowOutput> sendContractFromFlow(List<FlowInput> requests) {
        List<FlowOutput> results = new List<FlowOutput>();

        for (FlowInput req : requests) {
            FlowOutput out = new FlowOutput();
            try {
                // Fetch Opportunity & Account context
                Opportunity opp = [
                    SELECT Id, Name, Amount, CloseDate, Description,
                           Account.Name, Account.BillingStreet, Account.BillingCity
                    FROM Opportunity
                    WHERE Id = :req.opportunityId
                    LIMIT 1
                ];

                // Generate legal markdown document dynamically from CRM record
                String markdown = generateContractMarkdown(opp, req.recipientName);

                // Prepare API request
                SendDocumentRequest apiReq = new SendDocumentRequest();
                apiReq.title = String.isNotBlank(req.documentTitle) ? req.documentTitle : ('Agreement - ' + opp.Name);
                apiReq.markdown = markdown;
                apiReq.recipient_name = req.recipientName;
                apiReq.recipient_email = req.recipientEmail;
                apiReq.webhook_url = getSalesforceWebhookUrl();
                apiReq.metadata = new Map<String, String>{
                    'opportunity_id' => String.valueOf(opp.Id),
                    'account_name' => opp.Account != null ? opp.Account.Name : ''
                };

                // Execute Callout
                SendDocumentResponse apiRes = sendDocument(apiReq);

                // Store metadata back onto Opportunity
                opp.Signbee_Document_Id__c = apiRes.document_id;
                opp.Signbee_Signing_URL__c = apiRes.signing_url;
                opp.Signbee_Status__c = 'Out for Signature';
                update opp;

                out.documentId = apiRes.document_id;
                out.signingUrl = apiRes.signing_url;
                out.isSuccess = true;
            } catch (Exception ex) {
                out.isSuccess = false;
                out.errorMessage = ex.getMessage();
                System.debug(LoggingLevel.ERROR, 'Signbee Callout Failed: ' + ex.getMessage() + ' \n' + ex.getStackTraceString());
            }
            results.add(out);
        }
        return results;
    }

    /**
     * Core HTTP Callout execution against Signbee API
     */
    public static SendDocumentResponse sendDocument(SendDocumentRequest requestData) {
        HttpRequest req = new HttpRequest();
        req.setEndpoint('callout:Signbee_API/api/v1/send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setTimeout(120000); // 120 second timeout for enterprise reliability

        String jsonBody = JSON.serialize(requestData, true);
        req.setBody(jsonBody);

        Http http = new Http();
        HttpResponse res = http.send(req);

        Integer statusCode = res.getStatusCode();
        if (statusCode >= 200 && statusCode < 300) {
            return (SendDocumentResponse) JSON.deserialize(res.getBody(), SendDocumentResponse.class);
        } else {
            String errDetail = 'Signbee API Error (' + statusCode + '): ' + res.getBody();
            throw new SignbeeApiException(errDetail);
        }
    }

    /**
     * Helper to render dynamic markdown agreement from Salesforce Opportunity data
     */
    public static String generateContractMarkdown(Opportunity opp, String signerName) {
        String formattedAmount = opp.Amount != null ? ('$' + String.valueOf(opp.Amount.format())) : '$0.00';
        String closeDateStr = opp.CloseDate != null ? String.valueOf(opp.CloseDate) : String.valueOf(Date.today());

        String md = '# Master Services & Subscription Agreement\n\n';
        md += '**Provider:** B2bee Ltd\n';
        md += '**Client:** ' + (opp.Account != null ? opp.Account.Name : 'Client Organization') + '\n';
        md += '**Signer:** ' + signerName + '\n';
        md += '**Effective Date:** ' + closeDateStr + '\n\n';
        md += '## 1. Engagement & Commercial Terms\n\n';
        md += '| Term | Commitment |\n';
        md += '| :--- | :--- |\n';
        md += '| Total Contract Value | **' + formattedAmount + '** |\n';
        md += '| Reference Opportunity | ' + opp.Name + ' (' + opp.Id + ') |\n';
        md += '| Payment Schedule | Net 30 Days from Invoice Date |\n\n';
        md += '## 2. Scope of Services\n\n';
        md += (String.isNotBlank(opp.Description) ? opp.Description : 'Services defined in associated Statement of Work.') + '\n\n';
        md += '## 3. Legally Binding Electronic Signature\n\n';
        md += 'By signing electronically, both parties agree to all terms and conditions set forth herein under the provisions of the United States ESIGN Act and UETA regulations.';

        return md;
    }

    /**
     * Resolves the public Salesforce Site webhook URL from Custom Metadata or Settings
     */
    private static String getSalesforceWebhookUrl() {
        // Replace with your Salesforce Experience Cloud / Site Public Webhook URL
        return 'https://yourdomain.my.site.com/services/apexrest/webhooks/signbee';
    }
}

@RestResource(urlMapping='/webhooks/signbee/*')
global without sharing class SignbeeWebhookResource {

    // Store your webhook secret securely in a Protected Custom Metadata record
    private static final String WEBHOOK_SECRET = Signbee_Settings__c.getInstance().Webhook_Secret__c;

    public class WebhookEvent {
        public String event; // e.g. 'document.signed', 'document.viewed', 'document.declined'
        public WebhookData data;
    }

    public class WebhookData {
        public String document_id;
        public String status;
        public String timestamp;
        public String signed_pdf_url;
        public Map<String, String> metadata;
    }

    @HttpPost
    global static void handleWebhook() {
        RestRequest req = RestContext.request;
        RestResponse res = RestContext.response;

        try {
            // 1. Extract raw binary body and signature header
            String signatureHeader = req.headers.get('X-Signbee-Signature');
            Blob requestBodyBlob = req.requestBody;
            String rawJson = requestBodyBlob != null ? requestBodyBlob.toString() : '';

            // 2. Validate cryptographic signature
            if (!verifyHmacSignature(requestBodyBlob, signatureHeader, WEBHOOK_SECRET)) {
                System.debug(LoggingLevel.WARN, 'Signbee Webhook: Invalid HMAC Signature');
                res.statusCode = 401;
                res.responseBody = Blob.valueOf('{"error": "Unauthorized: Invalid Signature"}');
                return;
            }

            // 3. Parse validated JSON payload
            WebhookEvent evt = (WebhookEvent) JSON.deserialize(rawJson, WebhookEvent.class);
            if (evt == null || evt.data == null) {
                res.statusCode = 400;
                res.responseBody = Blob.valueOf('{"error": "Malformed Event Payload"}');
                return;
            }

            // 4. Dispatch processing based on event type
            processEvent(evt);

            res.statusCode = 200;
            res.responseBody = Blob.valueOf('{"status": "success"}');
        } catch (Exception ex) {
            System.debug(LoggingLevel.ERROR, 'Webhook Processing Failed: ' + ex.getMessage() + ' \n' + ex.getStackTraceString());
            res.statusCode = 500;
            res.responseBody = Blob.valueOf('{"error": "' + String.escapeSingleQuotes(ex.getMessage()) + '"}');
        }
    }

    /**
     * Verifies the HMAC-SHA256 signature using Salesforce Crypto library
     */
    public static Boolean verifyHmacSignature(Blob payloadBlob, String receivedSignature, String secretKey) {
        if (payloadBlob == null || String.isBlank(receivedSignature) || String.isBlank(secretKey)) {
            return false;
        }

        Blob secretBlob = Blob.valueOf(secretKey);
        Blob calculatedMac = Crypto.generateMac('HmacSHA256', payloadBlob, secretBlob);
        String calculatedHex = EncodingUtil.convertToHex(calculatedMac);

        // Case-insensitive comparison against hex digest
        return calculatedHex.equalsIgnoreCase(receivedSignature);
    }

    /**
     * Business logic for updating Salesforce records
     */
    private static void processEvent(WebhookEvent evt) {
        String docId = evt.data.document_id;
        String eventType = evt.event;

        // Retrieve corresponding Opportunity by Document ID or metadata
        String oppIdStr = (evt.data.metadata != null && evt.data.metadata.containsKey('opportunity_id'))
            ? evt.data.metadata.get('opportunity_id')
            : null;

        List<Opportunity> opps;
        if (String.isNotBlank(oppIdStr)) {
            opps = [SELECT Id, StageName, Signbee_Status__c FROM Opportunity WHERE Id = :oppIdStr LIMIT 1];
        } else {
            opps = [SELECT Id, StageName, Signbee_Status__c FROM Opportunity WHERE Signbee_Document_Id__c = :docId LIMIT 1];
        }

        if (opps.isEmpty()) {
            System.debug(LoggingLevel.WARN, 'No matching Opportunity found for Document ID: ' + docId);
            return;
        }

        Opportunity opp = opps[0];

        switch on eventType {
            when 'document.signed' {
                opp.Signbee_Status__c = 'Completed';
                opp.StageName = 'Closed Won';
                opp.Signbee_Signed_Date__c = System.now();
                update opp;

                // Download & attach signed PDF to Salesforce Files asynchronously
                if (String.isNotBlank(evt.data.signed_pdf_url)) {
                    System.enqueueJob(new AttachSignedPdfQueueable(opp.Id, evt.data.signed_pdf_url, 'Signed_Contract_' + docId + '.pdf'));
                }
            }
            when 'document.viewed' {
                opp.Signbee_Status__c = 'Viewed by Recipient';
                update opp;
            }
            when 'document.declined' {
                opp.Signbee_Status__c = 'Declined';
                update opp;
            }
        }
    }
}

public class AttachSignedPdfQueueable implements Queueable, Database.AllowsCallouts {
    private Id parentRecordId;
    private String pdfUrl;
    private String fileName;

    public AttachSignedPdfQueueable(Id recordId, String url, String name) {
        this.parentRecordId = recordId;
        this.pdfUrl = url;
        this.fileName = name;
    }

    public void execute(QueueableContext context) {
        try {
            HttpRequest req = new HttpRequest();
            req.setEndpoint(this.pdfUrl);
            req.setMethod('GET');
            req.setTimeout(60000);

            Http http = new Http();
            HttpResponse res = http.send(req);

            if (res.getStatusCode() == 200) {
                // 1. Create ContentVersion record
                ContentVersion cv = new ContentVersion();
                cv.Title = this.fileName;
                cv.PathOnClient = this.fileName;
                cv.VersionData = res.getBodyAsBlob();
                cv.Origin = 'H';
                insert cv;

                // 2. Link to parent Opportunity
                Id conDocId = [SELECT ContentDocumentId FROM ContentVersion WHERE Id = :cv.Id].ContentDocumentId;

                ContentDocumentLink cdl = new ContentDocumentLink();
                cdl.ContentDocumentId = conDocId;
                cdl.LinkedEntityId = this.parentRecordId;
                cdl.ShareType = 'V';
                cdl.Visibility = 'AllUsers';
                insert cdl;
            }
        } catch (Exception ex) {
            System.debug(LoggingLevel.ERROR, 'Failed to download and attach signed PDF: ' + ex.getMessage());
        }
    }
}

@isTest
private class SignbeeServiceTest {

    // Mock HTTP Responder
    private class SignbeeMockSuccess implements HttpCalloutMock {
        public HttpResponse respond(HttpRequest req) {
            HttpResponse res = new HttpResponse();
            res.setHeader('Content-Type', 'application/json');
            res.setBody('{"document_id":"doc_live_salesforce_123","signing_url":"https://signb.ee/sign/doc_live_salesforce_123","status":"sent"}');
            res.setStatusCode(200);
            return res;
        }
    }

    @testSetup
    static void setupTestData() {
        Account acc = new Account(Name = 'Acme Enterprise Corp');
        insert acc;

        Opportunity opp = new Opportunity(
            Name = 'Acme Global Expansion',
            AccountId = acc.Id,
            StageName = 'Proposal/Price Quote',
            CloseDate = Date.today().addDays(30),
            Amount = 50000.00,
            Description = 'Enterprise multi-year platform licensing agreement.'
        );
        insert opp;
    }

    @isTest
    static void testFlowCalloutSuccess() {
        Opportunity opp = [SELECT Id FROM Opportunity LIMIT 1];

        Test.setMock(HttpCalloutMock.class, new SignbeeMockSuccess());

        SignbeeService.FlowInput input = new SignbeeService.FlowInput();
        input.opportunityId = opp.Id;
        input.recipientName = 'Jane Doe';
        input.recipientEmail = 'jane.doe@acme.com';
        input.documentTitle = 'Enterprise MSA';

        Test.startTest();
        List<SignbeeService.FlowOutput> outputs = SignbeeService.sendContractFromFlow(
            new List<SignbeeService.FlowInput>{ input }
        );
        Test.stopTest();

        System.assertEquals(1, outputs.size(), 'Should return one result');
        System.assertEquals(true, outputs[0].isSuccess, 'Callout should succeed');
        System.assertEquals('doc_live_salesforce_123', outputs[0].documentId);

        Opportunity updatedOpp = [SELECT Signbee_Document_Id__c, Signbee_Status__c FROM Opportunity WHERE Id = :opp.Id];
        System.assertEquals('doc_live_salesforce_123', updatedOpp.Signbee_Document_Id__c);
    }

    @isTest
    static void testWebhookSignatureVerification() {
        String secret = 'test_webhook_secret_key_123';
        String payload = '{"event":"document.signed","data":{"document_id":"doc_live_salesforce_123","status":"signed"}}';
        Blob payloadBlob = Blob.valueOf(payload);

        Blob mac = Crypto.generateMac('HmacSHA256', payloadBlob, Blob.valueOf(secret));
        String validSignature = EncodingUtil.convertToHex(mac);

        Boolean isValid = SignbeeWebhookResource.verifyHmacSignature(payloadBlob, validSignature, secret);
        System.assertEquals(true, isValid, 'Signature verification should pass for valid HMAC');

        Boolean isInvalid = SignbeeWebhookResource.verifyHmacSignature(payloadBlob, 'invalid_sig', secret);
        System.assertEquals(false, isInvalid, 'Signature verification should fail for invalid HMAC');
    }
}