Callback

Server-To-Server Callback

Partners have the option to register a callback URL to receive the disposition information for a respondent prior to handling the respondent’s redirect. The registered URL will receive a POST request that contains the respondent_id, disposition, status, and parameters (any extraneous query string parameter).

Notice

Use of the optional server-to-server callback will not alter the functionality of the redirect.

As with any other communication in and out of the gateway, the request is signed using the Dynata signing algorithm. The expiration, access key, and signature will be passed via the dynata-expiration, dynata-access-key and dynata-signature header fields, having a signing string that is a SHA-256 hash digest of the request body as a lowercase hexadecimal string. The access key and secret key used to generate the request signature will be the same key pair used to sign redirects back to the partner.

Important!

As with the outbound, it is the responsibility of the partner to verify the validity of each request by evaluating the expiration, and ensuring that the signature is correct.

The partner’s endpoint should return a 200 HTTP status code upon successful receipt of the callback request. Upon receipt of a 200 HTTP status code, or exhaustion of the request timeout, the respondent will be immediately redirected back to the partner platform.

It’s very important that the callback request is processed as quickly as possible, the gateway has a strict timeout of 5 seconds on the HTTP request.

Example: Callback Request

POST /custom/path HTTP/1.1
host: partner-domain.com
dynata-expiration: 2021-12-31T01:01:01.001Z
dynata-access-key: abc123
dynata-signature: f99d5a123561442a13e009e7041ad864294ff7fcd227ba57de6a36e3e0fa9b75

{
    "disposition": 1,
    "status": 0,
    "parameters": {
       "some-custom-parameter": "some-value"
    },
    "respondent_id": "respondent-123"
}