Channel Partner Reporting - Postback

Postback Reporting allows our channel partners to receive real-time notifications about lead conversion events, directly from the Engine platform. With this capability, you can track and attribute conversions more efficiently and unlock powerful downstream actions, such as dynamic bidding, real-time rewards, and deeper analytics integrations.

Overview

Engine's Postback Reporting API sends event notifications via webhook (aka "postbacks") when a monetizable event (aka "funded loan", "conversion", or "payout event") occurs for a lead that originated from your traffic. Today, this means payout events — the same payout line items you see in any Looker or Invoice reports Engine provides. These postbacks are triggered the moment a monetized payout is recorded in our system.

How It Works

1. A user interacts with your experience and triggers a lead (and typically, a client tag*) to be passed into Engine.

2. The user completes a monetizable conversion (e.g., a funded loan)

3. The Financial Institution reports the conversion back to Engine (or, if a CPC campaign, it is triggered immediately when Engine logs the click event)

4. As soon as Engine records the monetizable event (either immediately or on incoming reporting from the Financial institution), Engine sends a postback to your system, using the URL you provide.

Example:

• A user clicks a CPC offer (CPC payout: $0.50) ➔ You get a postback.

• That same user also converts on a CPA offer (CPA payout: $100) ➔ You get another postback.

Each postback includes the payout amount (i.e. the bounty you will receive), the transaction ID, and your client tag* (if provided by you).

*For info and instructions on appending Client Tags to your leads posted to Engine for your own attribution, please see Appendix E: Appending Client Tags for Leads Posted to Engine

Implementation Requirements

To begin receiving postbacks, Channel Partners must provide the following:

• Postback URL: The endpoint we will send the postback to

  • Example: "yourUrl.com/postbackreporting"

• Method: Either GET or POST

  • Example: GET

• Payload format

  • For GET: Parameters can be path or query params in the URL

    • Example: https://partner.example.com/postback?payout=100.00&clientId=abc123&campaignId=email&engineLeadUuid=eadc3ae3-f817-4762-a65a-e46f0b1732b4

  • For POST: Parameters can be included either as query/path params, or in the request body as JSON

    • Example:

      Copy

      {
        "payout": "100.00",
        "transactionId": "eadc3ae3-f817-4762-a65a-e46f0b1732b4",
        "engineLeadUuid": "e7f5b06a-25e9-11ee-be56-0242ac120002",
        "clientId": "abc123", // optional client tag, if provided by Channel Partner
        "campaignId": "email", // optional client tag, if provided by Channel Partner
      }

• Your instruction to the Engine team on how to send - i.e. what to call and how to structure - each of the following available fields, in the postback

  • Payout amount: the dollar amount (e.g., 100.00)

    • Example: "in dollars with 2 decimals"

  • Transaction Id: the payout event UUID

    • This is Engine's Transaction ID, let us know if you want it called transactionId or if your API expects some other field in order to store it

    • Example: ?yourMappedTransactionId={engineTransactionId}

  • Your client tag(s): any identifier(s) you provide when posting the lead that you use for attribution on your end (e.g., abc123). Please provide the key of the client tag(s) desired, and we will include the value you provided for that lead for that tag.

    • Example: "I am sending Engine our subId to identify my users, and i want it passed back to me as userId in my postback. send me ?userId={subId}`

    • Note: If your API expects a real ID to be sent back (otherwise it would return an error), provide us the ID you want us to send when we test the postback connection. Please test this in advance, and give us a sample payload that will result in a success response to us.

  • Engine's Lead UUID: Engine's internal lead identifier. You are not required to receive/record this identifier, but referencing it when reaching out to the Engine team will make any investigation/troubleshooting much easier and quicker to process.

    • Example: "I do not send any of my own IDs as client tags, so I want to receive Engine's Lead UUID in postbacks to identify individual users. Send them to me as partnerClientId, so the postback contains ?partnerClientId={engineLeadUuid}

You must provide the Engine team with a request payload that you confirm will result in a success response (no errors on invalid IDs, etc). If you're not able to provide this (and have validated in advance), it will significantly slow down the setup process.

Handling Invalidations

Invalidations occur when a previously recorded payout is later canceled or revised. Reasons can include:

• Funded loan was canceled (within the Financial Institution partner's contract window)

• Financial Institution initially sent duplicate or erroneous data

• Either the Financial Institution or Channel partner's contract for this lead/conversion was updated retroactively

Invalidations are not common, and as such, currently, most Channel Partners do not opt into receiving invalidations via postback. If you want to receive invalidation events, let us know, otherwise we will not send notifications of any invalidations.

Example Invalidation Scenarios

Invalidations can be sent in your desired format, for example (but not limited to), some options can be:

• presence of a field denoting a conversion vs an invalidation (e.g. event = "converted" | "invalidated")

• negative payout amount (for the same Transaction Id)

• presence of a deletedAt timestamp (for the same Transaction Id)

Example URL for a postback using GET for an invalidation:

https://partner.example.com/postback?payout=100.00&clientId=abc123&campaignId=email&engineLeadUuid=eadc3ae3-f817-4762-a65a-e46f0b1732b4&event=invalidated

Example JSON body for a postback using POST for an invalidation:

{
  "payout": "100.00",
  "transactionId": "eadc3ae3-f817-4762-a65a-e46f0b1732b4",
  "engineLeadUuid": "e7f5b06a-25e9-11ee-be56-0242ac120002",
  "clientId": "abc123", // optional client tag, if provided by Channel partner
  "campaignId": "email", // optional client tag, if provided by Channel partner
  "event": "invalidated"
}

Summary

Postback Reporting is the fastest way to get real-time payout visibility and power advanced campaign logic. Setup is lightweight, flexible, and requires minimal work from your engineering team. Contact your Engine representative to get started, or request enablement through our Control Center support channels.

Current Support

• Postbacks can be sent for invalidations.

• We can differentiate:

  • Initial payout

  • Invalidation of payout (same transaction_id, possibly with negative payout)

  • New payout (new transaction_id, same lead)

Limitations / Future Support

• Future plans of postback reporting are to include lead events that occur before the conversion (e.g. offer click). At this time, only the conversion/payout event is available to send via postback.

For questions or to request setup, reach out to your Partner Solutions Manager or email [email protected]