Callbacks

Callbacks

The gateway supports a survey callback mechanism that requires a URL configuration.

Security

All callback requests are 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.

Response

The partner’s endpoint should return a 200 HTTP status code upon successful receipt of the callback request.

Tip

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.

---

Survey 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 survey callback will not alter the functionality of the redirect.

Survey Properties

Field	Type	Description
disposition	Integer	Disposition outcome code
status	Integer	Status describing the disposition’s reason
parameters	Object	Extraneous query string parameters passed in inbound (see note below)
respondent_id	String	Partner’s respondent ID

Note

About parameters

The parameters object contains only extraneous (custom/passthrough) query string key-value pairs that the partner included on the inbound URL. Reserved keys required for authentication, routing, or respondent profiling — such as respondent_id, language, access_key, expiration, signature, attributes, gender, birth_date, postal_code, and source — will not appear in parameters.

Typical examples of keys that will appear: ctx, partner-specific session IDs, tracking tokens, or any other custom key the partner appends to the inbound URL.

Example: Survey Callback

HTTP 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": {
       "ctx": "abc123",
       "partner-session-token": "98765-xyz",
       "reward_tier": "gold"
    },
    "respondent_id": "respondent-123"
}