Event Postback API

Overview#

The Event Postback API fires a named tracking event against an existing lead. Use it to signal downstream actions — such as phone call completions, form steps, quote views, or conversions — that occur after the initial lead submission. When an event is a conversion event, a revenue value can be passed to trigger payout processing and buyer postbacks.

The endpoint is typically called from your webflow or landing page JavaScript using the Pingtree SDK, but it can also be called server-side.

Endpoint#

POST /api/event/trigger

Authentication#

No token-based authentication header is required for this endpoint. Campaign identity is established through the cid field in the request body.

Request Parameters#

Body Parameters (JSON)#

Example Request#

curl -X POST "https://api.pingtree.com/api/event/trigger" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "cmp_9z8y7x6w",
    "event_id": "quote_viewed",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "pid": "src_abc123"
  }'

Conversion Event with Revenue#

curl -X POST "https://api.pingtree.com/api/event/trigger" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "cmp_9z8y7x6w",
    "event_id": "sale_completed",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "pid": "src_abc123",
    "revenue": 45.00
  }'

Example Responses#

Success — Event Fired#

{
  "status": 200,
  "message": "Event triggered successfully",
  "data": {
    "cid": "cmp_9z8y7x6w",
    "pid": "src_abc123",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "conversion_id": "",
    "conversion": false
  }
}

Success — Conversion Event Fired#

{
  "status": 200,
  "message": "Event triggered successfully",
  "data": {
    "cid": "cmp_9z8y7x6w",
    "pid": "src_abc123",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "conversion_id": "conv_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "conversion": true
  }
}

Error — Missing Event ID#

{
  "status": 400,
  "message": "event_id is required"
}

Error — Missing Transaction ID#

{
  "status": 400,
  "message": "transaction_id is required"
}

Error — Invalid Event ID#

{
  "status": 400,
  "message": "Invalid event_id for this campaign"
}

Error — Duplicate Event (deduplication enabled)#

{
  "status": 400,
  "message": "Duplicate event for this transaction_id"
}

Error — Source Inactive#

{
  "status": 403,
  "message": "Source Inactive"
}

Status Codes#

Tips#

• Event IDs must be pre-configured. The event_id value must match an event defined in the campaign's event settings. Contact your campaign manager to confirm available event IDs.
• Conversion events require revenue. If the event is marked as a conversion type in the campaign settings, omitting revenue returns a 400 error.
• Deduplication: If the campaign event has duplicate conversion disabled, firing the same event_id + transaction_id combination a second time returns a 400 duplicate error. Enable isDuplicate in event settings to allow repeated firing.
• Concurrent lock: The API applies a 2-second lock per transaction_id + event_id pair to prevent race conditions from duplicate HTTP requests. Retries within this window return a 403.
• SDK usage: When using the Pingtree JS SDK on a webflow, events are typically fired automatically based on user interactions. Direct API calls are for server-side or non-webflow implementations.