Callbacks

The gateway supports two independent callback mechanisms, each requiring its own registered URL configuration:

Survey Callback
Reconciliation Callback

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.

Response

The partner’s endpoint should return a 200 HTTP status code upon successful receipt of the callback 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).

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

Example: Survey Callback

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"
}

Reconciliation Callback

Partners may register a separate reconciliation callback URL to receive notifications when a respondent’s completion is reconciled (e.g., charged back or credited). This URL is configured independently from the survey callback URL.

The registered URL will receive a POST request containing details about the reconciliation event, including the reason, price adjustment, and previous conclusion data.

Reconciliation Properties

Field	Type	Description
`id`	`String`	Reconciliation event ID
`reason`	`Object`	Reconciliation reason
`price_adjustment`	`Object`	Amount and type of adjustment
`previous_conclusion`	`Object`	The original conclusion data, if available
`respondent_id`	`String`	Partner’s respondent ID
`quota_group_id`	`Integer`	Quota group ID
`project_id`	`Integer`	Project ID
`reconciliation_timestamp`	`Date`	Date of reconciliation

`reason`

Field	Type	Description
`type`	`String`	`QUALITY_CHECK_FAIL`
`sub_status`	`Enum`	Specific reason `QUALITY_REJECTION` or `JUMPER`

`price_adjustment`

Field	Type	Description
`amount`	`Float`	The value of the reconciliation.
`currency`	`String`	The partner’s currency code (ISO 4217). (example: `USD`)
`type`	`Enum`	The type of price adjustment. `CREDIT` or `CHARGEBACK`

`previous_conclusion`

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 above)
`conclusion_id`	`String`	Unique identifier for the conclusion
`conclusion_timestamp`	`Date`	Date of conclusion

Example: Reconciliation Callback

POST /reconciliation/callback HTTP/1.1
host: partner-domain.com
content-type: application/json
dynata-expiration: 2026-03-15T12:00:00.000Z
dynata-access-key: abc123
dynata-signature: a1b2c3d4e5f6...

{
  "reason": {
    "type": "QUALITY_CHECK_FAIL",
    "sub_status": "QUALITY_REJECTION"
  },
  "price_adjustment": {
    "amount": 1.5,
    "currency": "USD",
    "type": "CREDIT"
  },
  "previous_conclusion": {
    "disposition": 1,
    "status": 2,
    "parameters": {
      "ctx": "abc123",
      "partner-session-token": "98765-xyz",
      "reward_tier": "gold"
    },
    "conclusion_id": "550e8400-e29b-41d4-a716-446655440000",
    "conclusion_timestamp": "2019-12-31T18:30:00"
  },
  "respondent_id": "r1",
  "quota_group_id": 9,
  "project_id": 3,
  "reconciliation_timestamp": "2020-01-01T12:00:00"
}

Reconciliation Reasons

The following describes the reconciliation reasons and the type of price_adjustment.type they produce:

Reason Type	Sub Status	Price Adjustment Type	Description
`QUALITY_CHECK_FAIL`	`QUALITY_REJECTION`	`CHARGEBACK`	Respondent failed quality checks after completion
`QUALITY_CHECK_FAIL`	`JUMPER`	`CHARGEBACK`	Respondent failed quality checks after completion because they were identified as jumping survey questions