API v2: Deprecating error description & webhook X-Request-Signature header


(Spencer Hunter) #1

Hello Dwolla developer community!

We have incrementally rolled out functionality to our new API v2 over the past 6 months, and have since made refinements to the API prompting the need for deprecation. Although these are minor changes, they are necessary and improve security and usability. These impacting changes are released in a non-breaking way, allowing you to make a seamless transition.

Deprecation timeline: Both of these changes will happen on February 29, 2016.

What’s changing and why?

Removing error description in all API error responses
On November 12, 2015 we introduced a new message attribute into error JSON response bodies, which coincided with an overall change to how errors are returned in the API. As ValidationErrors continued to grow in the API, we turned to this spec for a solution. Conforming to this spec required usage of a message attribute, which is used to express a human readable message related to the current error. Moving forward, if your application relies on the description error response attribute you will want to transition to message which is currently a duplication of description.

Example non-validation error:
{
“code”: “InvalidAccessToken”,
“description”: “Invalid access token.”, ←— Will be removed
"message": “Invalid access token.”
}

Removing X-Request-Signature header from webhooks
In our continuous effort to improve security, we recently added a new X-Request-Signature-Sha-256 header to webhooks. This new HMAC-SHA256 signature will replace the current X-Request-Signature that exists today which relies on a SHA-1 HMAC hash. To validate webhook requests moving forward, you’ll generate a SHA-256 HMAC hash using your webhook’s secret along with the data sent in the body of the request, comparing it to the value of the X-Request-Signature-Sha-256 header.

Example Node.js implementation:
function validate_webhook_signature(body, webhook_secret, signature) {
var crypto = require(‘crypto’);
hash = crypto.createHmac(sha256, webhook_secret).update(body).digest(‘hex’);
return (hash == signature);
}

When will these changes happen?

As mentioned in the introduction to this thread, these changes will occur on Monday, February 29, 2016. To ensure a seamless transition, we recommend testing and implementing these changes in our Sandbox (UAT) environment prior to this date.

If you have any questions or comments, don’t hesitate to reach out. To stay up-to-date with the latest from the Dwolla API, review our changelog and subscribe to our mailing list.