PHP REST API场景下，如何接收DocuSign信封完成状态的回调请求

Great call ditching cron polling—webhooks (DocuSign calls this feature Connect) are way more efficient for real-time updates, especially when you’re already maxed out on scheduled tasks. Here’s a step-by-step guide to get this working with your existing PHP REST API setup:

1. Configure DocuSign Connect (Webhook) in the Admin Console #

First, you need to tell DocuSign where to send completion notifications:

• Log into your DocuSign Admin account and navigate to Connect (under the Integrations menu).
• Click Add Custom Connect Configuration to create a new webhook:
  • Name: Give it a clear, descriptive name (e.g., "My App Envelope Completion Webhook")
  • URL: Enter the public-facing URL of your PHP endpoint that will receive the callback (e.g., https://your-app.com/docusign-webhook-handler.php)
  • Event Triggers: Under "Envelope Events", check only Envelope Completed (you can add other events later if needed)
  • Payload Format: Choose JSON (it’s easier to parse in PHP, but XML works too if you prefer)
  • Authentication: Enable HMAC Signature and set a strong secret key—this lets you verify the request actually comes from DocuSign (critical for security). Save this key securely; you’ll need it in your PHP code.
  • Other Settings: Ensure "Active" is checked, and adjust retry settings if needed (DocuSign automatically retries failed requests by default)

2. Build the PHP Webhook Handler #

Create a PHP script at the URL you specified to process incoming callbacks. Here’s a minimal, secure example:

<?php
// Disable error display for production (log errors instead)
ini_set('display_errors', 0);

// Your HMAC secret from DocuSign Connect configuration
$HMAC_SECRET = 'your-strong-hmac-secret-here';

// Verify the request is legitimate using HMAC
$incomingSignature = $_SERVER['HTTP_X_DOCUSIGN_SIGNATURE_1'] ?? '';
$payload = file_get_contents('php://input');

// Generate the expected HMAC signature
$expectedSignature = base64_encode(hash_hmac('sha256', $payload, $HMAC_SECRET, true));

if ($incomingSignature !== $expectedSignature) {
    // Reject unauthorized requests
    http_response_code(403);
    exit('Unauthorized');
}

// Parse the JSON payload (adjust to simplexml_load_string if using XML)
$envelopeData = json_decode($payload, true);

// Extract key details
$envelopeId = $envelopeData['envelopeId'];
$envelopeStatus = $envelopeData['status'];

// Only process completed envelopes (double-check even though we filtered triggers)
if ($envelopeStatus === 'completed') {
    // Update your system's status here:
    // Example: Mark the corresponding record as signed in your database
    // $db->query("UPDATE your_table SET status = 'signed' WHERE docusign_envelope_id = ?", [$envelopeId]);

    // Handle idempotency: Check if this envelope was already processed to avoid duplicates
}

// Send a 200 OK response to confirm receipt (DocuSign stops retries once it gets this)
http_response_code(200);
echo 'Success';
?>

Key Handler Tips: #

• HMAC Verification: Never skip this! It prevents attackers from sending fake callback requests to your endpoint.
• Idempotency: Add a check in your system to ensure you don’t reprocess the same envelope multiple times—this handles any retries DocuSign sends if your endpoint didn’t respond the first time.
• Error Handling: Log errors instead of displaying them, and only return a 200 status when processing is successful. DocuSign will retry requests that return 4xx/5xx status codes.

3. Test the Webhook #

DocuSign lets you test the connection directly from the Connect configuration page:

• Click Test next to your new configuration.
• Choose a test envelope that’s already completed, or create a new one to trigger the completion event.
• Check your PHP script’s logs and your system’s database to confirm the status update worked as expected.

This setup will give you real-time updates the moment an envelope is completed—no cron jobs required, which is perfect for your current server setup!

内容的提问来源于stack exchange，提问作者Manoj Dhiman