Incentives

AI Tools

The incentives API allows you to search issued incentives in the platform. Additionally, the incentives webhook allows you to receive notifications of new incentives issued by the platform.

Incentive Webhook

Currently, the platform supports direct integration with Tremendous for incentive processing.

If you are processing incentives using another provider, or have your own custom solution, you can use the Incentives Webhook feature to have the platform automatically push all incentive requests to an endpoint that you control.

Enabling the Webhook

You can enable the webhook by contacting your account manager. You will need to provide the endpoint that will receive calls from the platform. Only a single destination endpoint is supported.

Triggering Events and Retries

The webhook is automatically called whenever an incentive is issued within the platform by any authorized user. The payload of the call is described below.

If your webhook endpoint is unavailable or returns a failure status code, the system will retry over the course of 8 hours with progressively longer delays before abandoning the attempt.

If the system abandons an attempt to call your webhook, the associated incentive remains active within QualRecruit. You can retrieve any missed incentives using the incentive API calls.

Incentive Payload

The payload is a JSON object with the following elements:

Element	Type	Description
Id	string	The GUID identifier of the incentive.
RespondentId	string	The GUID of the respondent record to which this incentive is associated.
ProjectId	string	The GUID of the project with which this incentive is associated.
PanelId?	string	The GUID of the panelist with which this incentive is associated. In very limited circumstances, the incentive may not have been associated with a panel record when it was issued, in which case the value may be null.
Name	string	The name of the respondent.
Phone	string	The phone number of the respondent in E.164 format, or empty string if none.
Email	string	The email address of the respondent.
Amount	string	The amount of the incentive, as a whole number. The platform does not permit fractional currencies in incentives, like cents or pence.
Currency	string	The currency of the incentive.
Description	string	The comment left by the initiator on the incentive. May be an empty string.
InitiatedBy	string	The email address of the user making the incentive request.
InitiatedOn	string	The ISO date and time the incentive was requested.
WebhookNonce	string	A GUID representing this webhook call. This value is guaranteed to be unique between calls.
WebhookExpires	string	The ISO date and time after which this payload should be discarded without acting on it.

Idempotency and Replay Prevention

In the case of retries, with the exception of the WebhookNonce, every call to your webhook for the same incentive Id is guaranteed to be identical. If the platform retries an incentive that you have already processed, you may discard the attempt and return a success status code.

The WebhookNonce is guaranteed to be unique with every call. Combined with the signature described below, you can ensure that your API only receives valid and authorized payloads that cannot be replayed.

Once a WebhookNonce is used, your API should ignore any other attempt to reuse it. To eliminate the need to indefinitely store a used WebhookNonce, the WebhookExpires value is used as an absolute limit on the validity of the webhook payload. If you receive a payload after the WebhookExpires date, you should discard the payload even if it is otherwise valid and even if the WebhookNonce has not yet been used.

Webhook Signature

Every payload is signed by the platform's RSA-2048 private key. You can retrieve the public portion of the platform's key by navigating to the Platform API section of the Admin Panel.

The payload is first hashed using the SHA256 hash algorithm, and then signed using the platform's RSA-2048 private key. The signature is then base-64 encoded and included in the X-Webhook-Signature header of the HTTP request to your endpoint.

As a best practice, you should perform the same hash on any received payload and validate the hash with the signature using the platform's public key as retrieved from the Admin Panel.

If the signature does not validate, or if the X-Webhook-Signature header is missing or empty, do not process the payload.

Responses & Rejecting Incentives

Except as described below, any response from your endpoint that does not describe success (status codes 200-299) is considered a failure and will invoke the platform's retry logic.

You may reject and cancel an incentive by returning a 424 Failed Dependency response. If the platform receives this response code, it will mark the incentive as cancelled and will remove the incentive from the respondent's/panelist's aggregate history of received incentives. The incentive will still appear within QualRecruit but will not count towards any totals.

If using the platform's Tremendous integration, cancelling an incentive using the 424 Failed Dependency response code does not cause the platform to issue a cancellation request to Tremendous. You are responsible for ensuring the incentive is cancelled with Tremendous.

Last updated on