What is a Conversion Webhook?

A Conversion Webhook is an HTTPS POST request sent to an endpoint you control whenever one of your user's conversions changes state. Unlike Postbacks, which send a GET request with query parameters, Conversion Webhooks send a POST request with a JSON body and a secret header. Configuring Conversion Webhooks allows you to reconcile transactions, update user balances, and run fraud or reporting pipelines in real time.

We support three Conversion Webhook types, each configurable independently per placement. All three share the same request body format - only the event field and the x-lootably-webhook-type header change.

Configuring your Conversion Webhooks

Begin by navigating to the Webhooks tab on your placement's settings page. Here, you can set an endpoint URL for each of the webhook types.

NOTE: You do not need to configure all three endpoints, only the endpoint(s) you would like to subscribe to.

Each placement also has a unique Webhook Secret which is included on every request so you can verify authenticity. You can rotate this value at any time from the same Webhooks tab.

Request Format

All Conversion Webhooks are sent as an HTTPS POST request with the following characteristics:

• Method: POST
• Content-Type: application/json
• User-Agent: Lootably-Webhook-Bot/1.0 (+https://documentation.lootably.com/docs/webhooks)

Conversion Webhooks are sent from a fixed set of Lootably egress IPs. If your system firewalls inbound traffic, please reach out to [email protected] to receive the latest list.

We provide a TypeScript type definition below for the request body JSON data.

Headers

Every Conversion Webhook includes the following Lootably-specific headers:

Body

The request body is always a JSON object with two top-level keys, event and data.

Multistep Conversions

When data.offerType is "multistep", the data object includes the following additional properties:

TypeScript Types

Below is the TypeScript definition for a Conversion Webhook's body.

// Types
import type InternalConversion from 'types/InternalConversion';

type ConversionWebhookBody<EventType extends 'approved' | 'pending' | 'rejected' = 'approved' | 'pending' | 'rejected'> = {
  event: EventType,
  data: {
    placementID: string,
    userID: string,
    transactionID: string,
    conversionTime: string,
    ip: string,
    countryCode: string,
    offerName: string,
    offerID: string,
    revenue: number,
    currencyReward: number,
    extraSubIDs: {
      sid2: string | null,
      sid3: string | null,
      sid4: string | null,
      sid5: string | null,
    },
  } & (
    | {
      offerType: 'singlestep',
    }
    | {
      offerType: 'multistep',
      multistepOfferPercentageComplete: number,
      goalID: string,
      goalDescription: string,
    }
  ),
};

export default ConversionWebhookBody;

Validating Webhooks

To validate that a Conversion Webhook originated from Lootably, compare the x-lootably-webhook-secret header against the Webhook Secret listed on your placement's Webhooks tab. If the values match, the request came from our system.

if(req.headers['x-lootably-webhook-secret'] !== process.env.LOOTABLY_WEBHOOK_SECRET) {
  return res.status(401).send('Invalid webhook secret');
}

If you suspect your Webhook Secret has been exposed, you can rotate it at any time from the Webhooks tab.

Response

Return a 2xx status code to acknowledge a Conversion Webhook. Any non-2xx response, or a request that times out, is treated as a failure.

Webhooks may be resent up to five times until a successful 2xx response is received.