Facebook Conversions API (Meta CAPI)

Send web, app, offline, and physical store conversion events from your data warehouse to Meta using the Conversions API (CAPI). This is Meta's recommended server-side integration for improving ad targeting, attribution, and measurement.

Meta's modern architecture centers on datasets, which unify website, app, offline/store, and messaging event data into a single pipeline. The Conversions API is the primary way to send events to your dataset.

For a full walkthrough with use-cases, see our step-by-step blog guide.

Features

Setup Guide - Reverse ETL

Step 1 - Create the Reverse-ETL Destination

1. Click on Reverse ETL in the Weld sidebar.
2. If this is your first Reverse-ETL sync, the setup guide starts automatically. Otherwise, click Add Reverse ETL Sync.
3. Find Facebook Conversions from the connector list and either select an existing connection or create a new one. You'll be prompted to authorize with your Meta account.

Step 2 - Target Details

The Facebook Conversions connection does not have additional configuration. This step is skipped.

Step 3 - Map Your Data

This is the most important step. You'll connect your SQL model to Meta's CAPI parameters.

Source Model

Select the SQL model that produces the event data you want to send. Your model should output one row per event.

Sync Mode

• Insert — Sends new events only (the only supported mode for CAPI)

WHERE event_time >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY))

Choose Identifier

Select the unique identifier to match records between source and destination. This is typically event_id or a unique row ID.

Field Mapping

Map columns from your SQL model to Meta CAPI parameters. Below is a reference for which fields to include and how to format them.

Weld automatically hashes all customer information parameters that require hashing (email, phone, name, city, etc.). You do not need to hash them yourself.

Required Fields

Recommended Fields (improve Event Match Quality)

The more customer information you send, the higher your Event Match Quality (EMQ) score, and the better Meta can optimize your campaigns.

Deduplication Fields

If you also send the same events via the Meta Pixel (client-side), include these fields to prevent double-counting:

fbq(
  "track",
  "Purchase",
  { value: 49.99, currency: "USD" },
  { eventID: "Purchase:order_456" },
);

Custom Data Fields (optional)

Step 4 - Schedule Sync

Choose how often to sync events to Meta. Meta recommends near-real-time delivery for best optimization results.

• Independent: The sync runs on its own schedule (e.g. every 15 or 30 minutes).
• Orchestration: The sync runs as part of a Weld orchestration workflow, after your upstream models refresh.

For most use-cases, we recommend syncing every 15-30 minutes.

Step 5 - Finalize and Run

Click Start Sync to save your configuration and begin sending events.

Verifying Your Setup

After your first sync completes, verify that Meta is receiving and matching your events:

1. Meta Events Manager → Test Events: Use Meta's Test Events tool to confirm server events are arriving. You can also use test_event_code in your payload during testing to route events to the test view without affecting production data.

2. Meta Events Manager → Overview: Check that your CAPI events appear under the correct dataset with the label "Server" as the connection method.

3. Event Match Quality (EMQ): Review the EMQ score for each event type (visible in Meta Events Manager). Aim for 6+ out of 10. If your score is low, add more customer information parameters to your SQL model.

4. Deduplication Check: If you're sending redundant events (Pixel + CAPI), verify in the Test Events tool that duplicate events are being properly merged, not double-counted.

5. Payload Helper: Use Meta's Payload Helper to validate your event payload structure. Meta also offers a Parameter Builder Library, a lightweight SDK for generating high-priority match keys following best practices.

Ongoing Monitoring

Setup is not a one-time task. Monitor these metrics weekly to maintain integration health:

For teams managing CAPI at scale, Meta's Dataset Quality API lets you monitor event quality, match rates, and diagnostics programmatically, which is useful for building automated alerts.

Common Issues