From 25bb8629d72a213acdd70627f91e265a59a0cea1 Mon Sep 17 00:00:00 2001 From: Melvyn Sopacua Date: Tue, 10 Oct 2017 16:21:43 +0200 Subject: [PATCH 1/2] Improve postback documentation: - Mention that the checksum is transmitted through the Digest header - Alter some sentences to clarify the process - Use the word permanent to stress that failures are fatal --- postback.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/postback.md b/postback.md index 47e2e0b..0f81d31 100644 --- a/postback.md +++ b/postback.md @@ -25,12 +25,12 @@ There is no deduplication. If the postback url returns a non 2xx http status code we will queue any new postbacks. In the meantime we will retry to deliver the first failed postback with an increasing interval (the first retry is within a few minutes). After 5 successive failed attempts we will send you an email. -We will include the attachment with the received response (if any). +We will include an attachment containing the received response (if any). When we receive a 2xx http status code we will mark the postback url as available and start sending the queued postbacks. ### Checksum -To verify that the postback responses are from SignHost you MUST verify our digital signature checksum. This signature is a hash of some parameters from the response and the sharedsecret. In order the generate the Checksum you will need a sharedsecret. +To verify that the postback responses are from SignHost you MUST verify our digital signature checksum. This signature is a hash of some parameters from the response and the sharedsecret. The checksum is transmitted via the `Digest` HTTP header. In order the generate the Checksum you will need a sharedsecret. The checksum is generated using the following formula: @@ -44,7 +44,7 @@ As you may have noticed the “pipe” sign ( | ) is used as the delimiter ### Request body formats -``` +```javascript { "Id": "b10ae331-af78-4e79-a39e-5b64693b6b68", "Status": 20, @@ -126,11 +126,10 @@ As you may have noticed the “pipe” sign ( | ) is used as the delimiter ### What happens if your postback URL is down or can't accept requests? -If the webhook URL doesn't return a 2xx HTTP response code, that POST request will be re-attempted with a random increasing interval. +If the webhook URL doesn't return a 2xx HTTP response code, that POST request will be retried with a randomly increasing interval. + +If a particular POST request is unsuccessful and is being retried, no other POSTs will be attempted until the oldest succeeds or is marked as failed. Postbacks marked as failed are permanent failures and will not be retried. Requests are marked failed after about 1 week since the request was created. -If a particular POST request is unsuccessful and is being retried, no other POSTs will be attempted until the first one succeeds or is marked as failed. -Requests are marked failed after about 1 week since the request was created. -Subsequent postbacks are deferred until the first completes. -Once the first postback request completes the defered requests will be processed sequentially. +Once the oldest postback request completes the deferred requests will be processed in sequence. -Since postback requests can ultimately fail, it's best to accept and store data on your end (with an HTTP 200 response to Signhost) for later processing to avoid data loss. +Since postback requests can ultimately fail, it's best to accept and store data on your end and return a HTTP 200 response to Signhost. You can then process the data out of band and prevent loss of transaction information due to a postback being marked as failed. From 9ffef6705e2886ae9b67c3172eaa9d5a19eb4839 Mon Sep 17 00:00:00 2001 From: Melvyn Sopacua Date: Sun, 15 Oct 2017 05:59:27 +0200 Subject: [PATCH 2/2] Fix where checksum is sent Apparently I missed the checksum in the data dictionary example and figured the mechanism would be consistent with uploading a file. Fix this. --- postback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/postback.md b/postback.md index 0f81d31..07f99e9 100644 --- a/postback.md +++ b/postback.md @@ -30,7 +30,7 @@ When we receive a 2xx http status code we will mark the postback url as availabl ### Checksum -To verify that the postback responses are from SignHost you MUST verify our digital signature checksum. This signature is a hash of some parameters from the response and the sharedsecret. The checksum is transmitted via the `Digest` HTTP header. In order the generate the Checksum you will need a sharedsecret. +To verify that the postback responses are from SignHost you MUST verify our digital signature checksum. This signature is a hash of some parameters from the response and the sharedsecret. The checksum is transmitted in the JSON post data. In order the generate the Checksum you will need a sharedsecret. The checksum is generated using the following formula: