Postback Reporting
This page describes how to take advantage of Engine by MoneyLion's Postback reporting capabilities
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.
For questions or to request setup, reach out to your Partner Solutions Manager or email [email protected]
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.
What's Supported
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
At this time, only the conversion/payout event is available to send via postback. Future plans of postback reporting are to include lead events that occur before the conversion (e.g. offer click).
How It Works
A user interacts with your experience and triggers a lead (and typically, a client tag*) to be passed into Engine.
The user completes a monetizable conversion (e.g., a funded loan)
The Financial Institution reports the conversion back to Engine (or, if a CPC campaign, it is triggered immediately when Engine logs the click event)
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.
If a lead converts on multiple offers, you may receive multiple postbacks for that same lead, each with a different transaction ID and payout amount.
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
GETorPOSTExample: GET
Payload Format
For
GET: Parameters can be path or query params in the URLExample: &#xNAN;
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 JSONExample:
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
transactionIdor if your API expects some other field in order to store itExample:
?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
subIdto identify my users, and i want it passed back to me asuserIdin 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}
The examples above show how a postback can look for either GET or POST requests. The names of the params here are examples of what the fields could be named, and how they could be structured, but Engine is able to adjust to your preferred structure - just please provide your preferred naming conventions and structure to us explicitly (both the method/URL and request body, if desired).
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.
If you choose not to receive invalidations via postback, your internal numbers are likely to have occasional mismatches with Engine's Looker/Invoice reports, which do incorporate invalidations (i.e. we remove any deleted payouts), and this will require reconciliation during monthly invoicing, if and when there are any invalidations that month. Therefore, while it is by no means required, we highly recommend building your ingestion logic to incorporate invalidations, and opting in for Engine to send them.
Example Invalidation Scenarios
Funded loan canceled
$100
-$100
None
Duplicate record sent
$100
-$100
None
Contraact updated retroactively
$100
-$100
$110 (with new Transaction ID)
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
deletedAttimestamp (for the same Transaction Id)
Example URL for a postback using GET for an invalidation:
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:
POST for an invalidation:Best Practices
Partners should treat postbacks as a production data pipeline, not just a notification.
Build for Idempotency
Your endpoint should safely handle duplicate deliveries.
Use Engine's Transaction ID as the unique identifier for a payout event. If you receive the same Transaction ID more than once, do not create a duplicate record.
Store Engine identifiers
We strongly recommend storing:
Transaction ID for the payout event
Engine Lead UUID for lead-level investigation
The Transaction ID is best for deduplicating payout records. The Lead UUID is best for reconciling reporting issues with the Engine team.
Send Client Tags
If you want to attribute payouts to your own users, placements, or campaigns, send client tags when posting leads to Engine.
Good examples include:
clientIdcampaignIdsubidsourceId
Do not send PII in client tags.
Be Explicit About Your Payload Contract
When requesting setup, provide the exact structure your endpoint expects:
request method
full URL
required headers
parameter names
sample success response
sample payload that you have already validated
This reduces setup time and avoids back-and-forth during testing.
Handle Invalidations Correctly
Even if invalidations are infrequent, your ingestion logic should support them.
At minimum, your system should be able to:
reverse or mark a prior payout as invalid
preserve the original Transaction ID
handle a replacement payout arriving separately with a new Transaction ID
If you ignore invalidations, your internal reporting may not match invoice totals.
Return a Clear Success Response
Your endpoint should return a fast, clear success response when a postback is accepted.
If your system performs heavier downstream processing, queue the payload internally after receipt instead of doing all processing synchronously in the request cycle.
Log Requests for Troubleshooting
Keep a record of the raw inbound request, response status, and receipt timestamp.
This makes it much easier to investigate:
missing payouts
duplicate deliveries
field mapping issues
disputes during invoice reconciliation
Test Before Go-live
Before asking Engine to enable production delivery, confirm that:
your endpoint is reachable
authentication works
your endpoint accepts the exact payload format requested
your system stores the identifiers and payout values correctly
your team knows how invalidations will be handled
Providing a tested sample payload that returns success will speed up launch significantly.
Monitor for Failures
After go-live, monitor your endpoint for:
non-2xx responses
authentication failures
timeout errors
drops in expected postback volume
If you detect an issue, contact the Engine team with the approximate timestamp, Transaction ID, and Engine Lead UUID when available.
Last updated
Was this helpful?