Docusign eventNotification is failing with error 400

Question

I am using Docusign's REST API to create and send envelopes. I've included eventNotifications with requireAcknowledgment as true to get requests from Docusign whenever there's status change. I used ngrok while development and testing and everything worked as expected.

I've moved the project online and have edited the eventNotification's url to live url with https and that's when all the callbacks are getting logged in failed section in Docusign's admin panel.

The error message shown in admin panel is -

'https://xxx.xxxxxxx.com/webhook.php :: Error - The remote server returned an error: (400) Bad Request.'

I've downloaded the failed request's xml body and tried sending a request through postman and it worked as expected. Iv'e tried everything to debug this error and have not found error at my end.

Edit: The code that I've tried with is the same code from DocuSign's webhook sample page -

    $data = file_get_contents('php://input');
$xml = simplexml_load_string ($data, "SimpleXMLElement", LIBXML_PARSEHUGE);
$envelope_id = (string)$xml->EnvelopeStatus->EnvelopeID;
$time_generated = (string)$xml->EnvelopeStatus->TimeGenerated;

$files_dir = getcwd() . '/' . $this->xml_file_dir;
if(! is_dir($files_dir)) {mkdir ($files_dir, 0755);}
$envelope_dir = $files_dir . "E" . $envelope_id;
if(! is_dir($envelope_dir)) {mkdir ($envelope_dir, 0755);}

$filename = $envelope_dir . "/T" . 
    str_replace (':' , '_' , $time_generated) . ".xml"; // substitute _ for : for windows-land
$ok = file_put_contents ($filename, $data);

if ($ok === false) {
    error_log ("!!!!!! PROBLEM DocuSign Webhook: Couldn't store $filename !");
    exit (1);
}
// log the event
error_log ("DocuSign Webhook: created $filename");

if ((string)$xml->EnvelopeStatus->Status === "Completed") {
    // Loop through the DocumentPDFs element, storing each document.
    foreach ($xml->DocumentPDFs->DocumentPDF as $pdf) {
        $filename = $this->doc_prefix . (string)$pdf->DocumentID . '.pdf';
        $full_filename = $envelope_dir . "/" . $filename;
        file_put_contents($full_filename, base64_decode ( (string)$pdf->PDFBytes ));
    }
}

I've also tried with simple code that just sets header to 200

http_response_code(200);

Answer 1

Sorry you're having so much trouble with the webhook feature. Hopefully this answer will be of assistance.

1. Try a test PHP program to check connectivity, etc:

<?php
header('Content-Type: text/html');
echo "OK!";
$h = fopen('/tmp/listener_access.log', 'a');
if ($h) {
    $now = DateTime::createFromFormat('U.u', microtime(true), new DateTimeZone('UTC'));
    fwrite ($h,  $now->format ("Y-m-d_l.h.i.s.v "));
    fwrite($h, $_SERVER["REMOTE_ADDR"] . " " . $msg . "\n");
    fclose($h);
} else {
    error_log ("### Could not open log file!");
}

Store it as ok.php in your web server directory. Then try (from a browser on a different network) to reach https://yourserver.company.com/ok.php You should see "ok" in the browser window.

Then use the same url in your eventNotification section of your Envelopes::create call to see if it all works. You should see a success in the Connect log, etc.

2. Stepwise debugging of your PHP listener

There are a number of issues to rule-out (as diagnosticians say) with your php listener app.

1. Basic connectivity with the listener. Since DocuSign is receiving a 400 error from your app, connectivity is ok.

2. Platform errors with your app. This is a problem with your PHP software stack setup that is causing the stack (not your PHP app, per se) to reject the request.

   The usual indicator for this is your web server's error log. Have you looked at it? What is on the logging line where you see the 400 response from your server to DocuSign? If you don't see the 400 response to DocuSign then something is wrong with your web server's setup.

3. A common platform error with PHP and other stacks when default settings are used is maximum_post_size_exceeded. This is happens if you have requested that DocuSign include your envelope's documents in the notification message.

   A good test is to temporarily change your envelope create code to not include documents in the notification messages.

   Fixes: a good fix is to not include the envelope documents in the notification message. Instead, after the message is received, make separate API calls to retrieve the documents.

   The other fix is to increase the maximum post body size. You may need to increase it both in the PHP settings and in the underlying web server's settings too. (By the way, which web server are you using?)

4. You are processing the incoming notification in the response thread of your server/php app. This really isn't the best technique (I will be updating the DocuSign example page in the future with this information.)

The best technique is to use the following pattern:

1. Receive the incoming notification message from DocuSign
2. Put the message onto a reliable FIFO queue
3. Respond to DocuSign with a 200 response.


Then, in a separate thread of execution, a 
different software application "works off" the 
entries in the queue.

Your web server, for example, may be timing out your PHP program. This probably isn't happening in your case, but others may experience this.

5. I think I would, next, add more debugging statements to your PHP program to try and understand what is happening to it. You can either do this with error-log or copy the technique from my example (above) and write to a file in /tmp. (Assuming a Linux server.)

   The other option is to increase the debugging level of the php stack itself, or of your web server, or both.

3. Last thoughts

400 in the DocuSign logs usually indicates that DocuSign reached your server and it returned a 400 status code. This can be confirmed by examining your server log (regular or error), there should be a matching entry.

If there isn't an entry in your server log, but the "ok.php" program from above does work, then it would be time to comment out big chunks of code from your PHP program, and then do another test from DocuSign. Eventually, using a binary-search technique (See step 8 in the article), you find the code that is causing the problem.

Commenting out code as part of a binary-search to find the bug is a very common, and powerful debugging technique.

HTH, Larry