Postbacks

Configure postback URLs to notify ad networks when installs are attributed.

GET /api/v1/postbacks

List postback configurations for an app.

Authentication: JWT required


curl "https://api.attributehq.com/v1/postbacks?app_id=YOUR_APP_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response (200 OK):


{
  "success": true,
  "data": {
    "postbacks": [
      {
        "id": "pb_abc123",
        "app_id": "YOUR_APP_ID",
        "media_source": "facebook",
        "postback_url": "https://www.facebook.com/tr?id=123&ev=Install&nonce={device_id}",
        "http_method": "GET",
        "active": true,
        "created_at": "2025-01-15T10:30:00Z"
      }
    ]
  }
}

POST /api/v1/postbacks

Create a new postback configuration.

Authentication: JWT required


curl -X POST https://api.attributehq.com/v1/postbacks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "media_source": "facebook",
    "postback_url": "https://www.facebook.com/tr?id=123&ev=Install&nonce={device_id}&campaign={campaign_id}",
    "http_method": "GET"
  }'

Request Body:

Field	Type	Required	Description
`app_id`	string	Yes	App UUID
`media_source`	string	Yes	Ad network name (e.g., `facebook`)
`postback_url`	string	Yes	URL template with macros
`http_method`	string	No	`"GET"` (default) or `"POST"`
`active`	boolean	No	Default: `true`

URL Macros

Use these macros in your postback URL — they’re replaced with actual values when the postback fires:

Macro	Description	Example
`{app_id}`	App UUID	`770e8400-...`
`{device_id}`	IDFA or GAID	`A1B2C3D4-...`
`{media_source}`	Ad network from click	`facebook`
`{campaign_id}`	Campaign from click	`summer_campaign`
`{match_type}`	Attribution method	`device_id`
`{install_time}`	ISO 8601 timestamp	`2025-01-15T10:30:00Z`
`{click_time}`	ISO 8601 timestamp	`2025-01-14T08:15:00Z`
`{confidence}`	Match confidence	`100`

Errors: 400 validation, 409 postback already exists for that media source

PUT /api/v1/postbacks/:id

Update a postback configuration.

Authentication: JWT required


curl -X PUT https://api.attributehq.com/v1/postbacks/pb_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

DELETE /api/v1/postbacks/:id

Delete a postback configuration.

Authentication: JWT required

POST /api/v1/postbacks/:id/test

Send a test postback with sample data.

Authentication: JWT required


curl -X POST https://api.attributehq.com/v1/postbacks/pb_abc123/test \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/v1/postbacks/logs

View postback delivery logs.

Authentication: JWT required


curl "https://api.attributehq.com/v1/postbacks/logs?app_id=YOUR_APP_ID&limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response includes per-log: resolved URL, status code, response body, error message, attempt number, timestamps.

Ad Network Templates

Facebook


https://www.facebook.com/tr?id=YOUR_PIXEL_ID&ev=Install&nonce={device_id}&cd[campaign_id]={campaign_id}

Google Ads


https://www.googleadservices.com/pagead/conversion/YOUR_CONVERSION_ID/?label=YOUR_LABEL&value=0&guid=ON&script=0&dev_token={device_id}

TikTok


https://analytics.tiktok.com/api/v2/conversion?event=CompleteRegistration&context[ad][callback]={device_id}&context[ad][campaign_id]={campaign_id}