Conversion Tracking

The Google Ads integration uploads click conversions to Google Ads when Pipedrive automations fire a webhook. Each configured conversion action maps to a discrete Google Ads conversion action with a name and value.

Flow

flowchart TD A[Webhook Received] --> B{Basic Auth valid?} B -- No --> Z0[Return 401 Unauthorized] B -- Yes --> C{Tracking enabled?} C -- No --> Z1[Return success: disabled] C -- Yes --> D{Conversion name found?} D -- No --> Z2[Return error: unknown conversion] D -- Yes --> E[Fetch deal from Pipedrive] E --> F{GCLID present?} F -- No --> Z3[Return error: GCLID not found] F -- Yes --> G[Upload conversion to Google Ads] G -- Success --> H[Log success, return 200] G -- CLICK_NOT_FOUND --> I[Queue for retry] G -- Other error --> J{Permanent or transient?} J -- Permanent --> K[Log error, return 202] J -- Transient --> L[Return 502 for Pipedrive retry]

Conversion Upload

When a webhook fires, the system:

  1. Authenticates the request via HTTP Basic Auth and identifies the company.
  2. Looks up the conversion action by name from the request body (conversion field).
  3. Fetches the deal from Pipedrive using the automation user’s token.
  4. Extracts the GCLID from the configured deal field.
  5. Generates a unique orderId in the format pd-{dealId}-{groupId}-{timestamp} for deduplication.
  6. Uploads the conversion via the Google Ads uploadClickConversions endpoint to the child account.
  7. Records the result in the conversion log.

GCLID Too New (CLICK_NOT_FOUND)

Google Ads can take several hours to process new ad clicks before they become available for conversion uploads. If the Google Ads API returns a CLICK_NOT_FOUND error:

  1. The conversion is automatically queued in the retry queue with type gads_click_not_found.
  2. The queue retries every 30 minutes.
  3. Retries continue until the configured Retry TTL expires (default: 12 hours).
  4. The webhook returns HTTP 200 with { success: true, queued: true } so Pipedrive does not retry.

See Retry Queue for details.

Error Handling

Upload errors are categorized as permanent or transient:

  • CLICK_NOT_FOUND – The GCLID is too new. Queued for automatic retry (see above).
  • Other permanent failures (e.g., invalid GCLID, partial failure from Google Ads) – The webhook returns HTTP 202 with retryable: false so Pipedrive does not retry.
  • Transient failures (e.g., authentication errors, server errors) – The webhook returns HTTP 502 so Pipedrive can retry the request.

All errors are recorded in the conversion log and, when applicable, trigger a failure notification email (category: gads_upload_failed).

Previous Configuration Next Retry Queue