InviteBox can be configured to make server-to-server calls to your application on the following events:

  • When a user makes a post to social channel.
  • When a referral visits your site (via referral link) or completes a referral goal - depending on the way your campaign is configured.

The former event is useful, for example, when you would like to generate unique discount codes for every user in an instant reward campaign. The latter option is useful for automating referral rewards in your application.

To enable this functionality, go to Widget settings -> Integration and click "Show API settings". Set "Reward callback" to the URL on your server to be called. Copy the "Secret key" value - this will be passed as a parameter to your callback and your application should check this value to prevent unauthorized access. 

The callback should accept POST requests with the following parameters:

  • secret - the secret key found in the widget settings as described above
  • event - the type of event that triggered the callback. This can take one of the following values:
    • post - the callback is invoked on user making a post
    • referral - the callback is invoked on referral visit / conversion
    • entry - the callback is invoked when a new participant enters the campaign
  • goal (if event = referral) - "true" if the campaign participant reached the goal.
  • referrer_extra_vars - in the latter scenario, a JSON-encoded object containing extra data set via setExtraVar Javascript API as described here
  • referrer_email - the email address that the referrer supplied when entering the campaign (if available)
  • visitor_email - the email address of referral (invitee), is available only on conversion even
  • invited_by - the email address of referrer, is available only when event is entry

The callback must return a JSON object. When the callback invoked on user making a post, the content of this object can be referenced in the text on the "thank you" page of the widget using [varname] placeholder where varname is the name of the object property. For example if you return {"coupon_code" : "ABCD12345"}, you can use "Thank you for spreading the word! Your coupon code is [coupon_code]." as the text. The returned JSON object is also available to the Javascript code on your page (or the one invoked by using "Execute Javascript code" reward) via "invitebox.secretExtra" reference. For example, to put promo code in a field like we do on, you could use something like this (using jQuery): $('#promo_code').val(invitebox.secretExtra.coupon_code);

Here's an example of server-side code in Python (using Django framework) from our own (instant reward-based) promo action:

def reward_callback(request):
    if request.method != "POST":
        return HttpResponseNotAllowed(["POST"])
    if request.POST.get('secret', None) != "our secret key":
        return HttpResponseForbidden()
    coupon = Coupon.objects.create()
    return HttpResponse(simplejson.dumps({"coupon_code" : coupon.code}),

And another example used by InviteBox's referral program (goal-based campaign):

def referral_callback(request):
    if request.method != 'POST':
        return HttpResponseNotAllowed(['POST'])
    if request.POST.get('secret', None) != 'our secret key':
        return HttpResponseForbidden()
    if request.POST.get('event',None) == 'referral':
        referrer_extra_vars = simplejson.loads(request.POST['referrer_extra_vars'])
        referrer = User.objects.get(id=referrer_extra_vars['user_id'])
        account = referrer.get_profile()
                                       note='main referral program')
        account.available_impressions += 500
    return HttpResponse(simplejson.dumps({}),