Docs/ Reference/ Webhooks
Webhooks

Webhooks (Global Postbacks)

Get notified in real time when transactions or campaigns change. Instead of polling the API, register a webhook URL and Cuelinks will POST (or GET) event data to your endpoint automatically. Configure up to 10 webhooks per event type from your publisher dashboard.

⚡
Webhooks are configured in the dashboard today. API-based webhook management (read/write:webhooks) is on the roadmap. This page documents the event types, payloads, and behavior so you can build your receiving endpoint.
Event types
TypeTriggers whenUse case
Transaction Update Status changes A transaction moves to pending, validated, payable, rejected, or paid. Subscribe to specific statuses or all of them.
Campaign Update Campaign lifecycle A campaign goes live, gets paused, or a new campaign is created. Filter by country.
Transaction Update payload

Fired when a transaction's status changes. You choose which statuses trigger the webhook: pending, validated, payable, rejected, paid.

MacroTypeDescription
{transaction_id}integerUnique transaction ID.
{campaign_id}integerCampaign ID.
{campaign_name}stringAdvertiser/campaign name.
{transaction_date}dateDate of the transaction.
{transaction_timestamp}datetimePrecise timestamp.
{status}stringCurrent status: pending, validated, payable, rejected, paid.
{sale_amount}floatOrder value.
{user_commission}floatYour commission.
{currency}stringCurrency code (default: INR).
{transaction_reference_id}stringMerchant's order/reference ID.
{aff_sub}stringSub ID 1 from the click.
{subid2} – {subid5}stringAdditional sub IDs.
{referrer_url}stringPage that initiated the sale.
{ip_address}stringVisitor's IP address.
{extra_info}stringAdditional data from the network.
{source}stringTransaction source.
Campaign Update payload

Fired when a campaign's status changes or a new campaign is created. You choose which events to subscribe to:

EventFires when
liveCampaign approved or reactivated (genre → approved_for_all or approved_for_selected).
pausedCampaign paused or deleted.
new_campaignNew campaign created on the platform.
MacroTypeDescription
{campaign_id}integerCampaign ID.
{campaign_name}stringCampaign name.
{campaign_status}stringCurrent status: Active, Paused, New.
{campaign_type}stringPayment model: CPS or CPC.
{campaign_country}stringCountry where the campaign runs.
{campaign_url}stringCampaign destination URL.
{update_type}stringEvent type: paused, live, or new_campaign.
{update_date}dateDate of the change.
{update_timestamp}datetimePrecise timestamp of the change.
How webhooks work

1. Register — Go to Global Postback in your dashboard. Choose Transaction Update or Campaign Update. Set your URL and select which events to subscribe to.

2. Map fields — Configure which macros map to which parameter names. Add constant parameters (like an auth secret) that are always included.

3. Test — Use the TEST button to send a sample payload to your URL before going live. Verify your endpoint returns 200.

4. Go live — Save the webhook. Events are delivered in real time via Sidekiq background jobs.

Example: Transaction webhook (POST)
POST https://your-app.com/webhooks/cuelinks

{
  "txn_id": 1234567,
  "campaign": "Flipkart",
  "status": "validated",
  "amount": "1500.00",
  "commission": "67.50",
  "sub_id": "user_7",
  "secret": "your-constant-param"
}
Example: Campaign webhook (GET)
GET https://your-app.com/webhooks/campaigns
  ?id=4821
  &name=Flipkart
  &event=live
  &type=CPS
Delivery behavior
PropertyDetails
HTTP methodsGET (params in URL) or POST (params in body, form-encoded).
RetriesUp to 10 retries with exponential backoff on non-2xx responses.
Auto-disableAfter 10 consecutive failures, the webhook is automatically set to inactive. You'll receive an email notification.
Max webhooks10 transaction webhooks + 10 campaign webhooks per publisher account.
DeliveryAsynchronous via background queue. Near real-time (<30 seconds typical).
OrderingNot guaranteed. Use {transaction_id} or {update_timestamp} for deduplication.
💡
Best practices
Respond with 200 quickly — do heavy processing asynchronously. Use a constant parameter as a shared secret to verify requests are from Cuelinks. Store the {transaction_id} to deduplicate retries.
← PreviousInvoice Transactions