Destinations

Forward conversion events to Meta, Google Ads, GA4 and your own signed webhooks, and sync audience membership to webhooks and Meta Custom Audiences.

Destinations forward conversion events, and for webhooks and Meta also audience membership, to the systems you run your marketing in. Every destination starts in a safe state, can be tested with a synthetic event, and exports nothing until you enable it.

In this page

  • How delivery works
  • Destination types
  • Create a destination
  • Event mapping
  • Lifecycle and test mode
  • When Kentro GO is stopped
  • Test sends
  • Google Ads offline conversions
  • Webhooks
  • Audience membership
  • Deliveries and what accepted means
  • Replays

How delivery works

  • Mapped events of an enabled destination are delivered in the background. Each delivery is retried with exponential backoff (2^attempts x 30 seconds, at most 1 hour; a provider's Retry-After is honored instead) for up to 8 attempts, and every outcome is listed in the delivery history.
  • While Kentro GO is stopped for your workspace, nothing is sent to any destination. See "When Kentro GO is stopped".
  • Consent is checked again when a delivery is sent: an ad network (Meta Conversions API, Google Ads) receives a person only with an explicit marketing grant and no GPC signal in their consent record, whatever consentPurpose the destination stores.
  • Properties in strict privacy mode never send to ad networks. Quarantined events and redacted server events are never sent.
  • The event's own consent purpose never authorizes an export: a functional server order is collected without marketing consent, but reaches Meta or Google Ads only for a person with an explicit marketing grant.

Destination types

destinationconfig (stored and returned)credentials (write-only, encrypted at rest)
meta_capipixelId (5 to 32 digits), optional apiVersion such as v26.0, optional testEventCode (up to 64 letters, digits, _ or -). For audience uploads, set together: adAccountId (act_ plus digits, or the digits alone) and goConnectionId (the id of your Kentro GO Meta connection)accessToken (10 to 2,048 characters)
google_ads_offlinecustomerId (123-456-7890 or 10 digits), conversionAction (customers/<id>/conversionActions/<id>), optional loginCustomerId, credentialSource: "go_connection", goConnectionId, optional customerMatchTermsAccepted (stored; Google Ads destinations take no audience membership, see "Audience membership")none: Kentro uses your Kentro GO Google Ads connection
ga4_mpmeasurementId (G- plus 4 to 20 upper-case letters or digits)apiSecret (8 to 256 characters)
webhookurl (https:// with a public host name, up to 2,048 characters)signingSecret (16 to 256 characters)

Credentials are never returned; every destination reports hasCredentials and credentialSource (stored, go_connection or null) instead, plus testMode, deliveryMode (test or live), audienceSync (whether its type takes audience membership, see "Audience membership") and, in test mode, a testModeNote. A meta_capi config that sets only one of adAccountId and goConnectionId answers 400. In Kentro GO, the Pixel page's Destinations tab creates and edits all four types (click New destination).

Create a destination

curl -sS https://apis.kentro.live/pixel/v1/destinations \
  -H "Authorization: Bearer $KENTRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "meta_capi",
    "name": "Meta dataset",
    "propertyId": "0192f0c4-6d1e-7a52-9c1f-3b1f2c7f9a10",
    "config": { "pixelId": "123456789012345", "testEventCode": "TEST12345" },
    "credentials": { "accessToken": "YOUR_META_ACCESS_TOKEN" },
    "eventMapping": [
      { "source": "commerce.order_paid", "target": "Purchase" },
      { "source": "marketing.lead_captured", "target": "Lead" }
    ],
    "consentPurpose": "marketing"
  }'
{
  "id": "0192f0ca-5e6f-7081-9293-a4b5c6d7e8f9",
  "propertyId": "0192f0c4-6d1e-7a52-9c1f-3b1f2c7f9a10",
  "destination": "meta_capi",
  "name": "Meta dataset",
  "status": "configured",
  "testMode": true,
  "deliveryMode": "test",
  "testModeNote": "Test mode: every delivery is sent with config.testEventCode and shows only in Events Manager > Test Events; nothing reaches the live dataset.",
  "config": { "pixelId": "123456789012345", "testEventCode": "TEST12345" },
  "eventMapping": [
    { "source": "commerce.order_paid", "target": "Purchase", "fields": {}, "enabled": true },
    { "source": "marketing.lead_captured", "target": "Lead", "fields": {}, "enabled": true }
  ],
  "consentPurpose": "marketing",
  "mappingVersion": 1,
  "lastDeliveryAt": null,
  "error": null,
  "hasCredentials": true,
  "credentialSource": "stored",
  "audienceSync": true,
  "createdBy": "7d1f2e3a-4b5c-4d6e-8f90-1a2b3c4d5e6f",
  "createdAt": "2026-10-09T18:10:00.000Z",
  "updatedAt": "2026-10-09T18:10:00.000Z"
}
  • propertyId is optional; when set it must belong to your workspace (400 PROPERTY_NOT_FOUND). Without it, the destination receives the events of every property of the workspace.
  • A config.goConnectionId is checked with Kentro GO when you create the destination, and when a PATCH links another connection. A connection that is not one of your workspace's answers 400 GO_CONNECTION_NOT_FOUND, a connection of another provider (a Meta connection on a Google Ads destination, for example) answers 400 GO_CONNECTION_PROVIDER_MISMATCH, and 503 GO_CONNECTION_UNVERIFIED means Kentro GO could not confirm the connection right now: try again in a minute. Nothing is saved in these cases.
  • consentPurpose (marketing by default, analytics or functional) is the consent rule GA4 and webhook destinations apply to a person's consent record before anything about them is exported. marketing needs an explicit marketing grant, and no GPC signal on a property that honors GPC. analytics follows the person's analytics choice and, without one, the property's analytics consent settings. functional exports unless the person denied functional consent. Ad networks always require an explicit marketing grant and no GPC signal.
  • testMode is ignored on creation: every destination starts with status: "configured" and testMode: true.

Event mapping

eventMapping is a list of up to 50 entries { "source", "target", "enabled" }, each with an optional fields object of up to 50 pairs (names up to 64 characters, values up to 256). fields shapes the data object of webhook deliveries (see "Webhooks"); Meta, GA4 and Google Ads deliveries and test sends do not use it. source must be a builtin or an active custom event of your workspace, and neither a reserved event nor the deprecated marketing.product_viewed. A mapping saved earlier on marketing.product_viewed keeps matching commerce.product_viewed events. Duplicates of the same source and target are refused; enabled defaults to true.

DestinationValid targets
meta_capiA Meta standard event (Purchase, Lead, CompleteRegistration, AddToCart, InitiateCheckout, ViewContent, Search, Subscribe, Contact, Schedule) or a custom event name: a letter, then letters, digits or underscores, at most 50 characters.
ga4_mpA Measurement Protocol event name: a letter, then letters, digits or underscores, at most 40 characters, not a reserved GA4 name, app-only name or reserved prefix.
google_ads_offlineA conversion action resource name, customers/<id>/conversionActions/<id>.
webhook1 to 100 letters, digits, dots, colons, dashes or underscores.

Invalid mappings answer 400 EVENT_MAPPING_INVALID with an errors array. Changing the mapping with PATCH increments mappingVersion.

Lifecycle and test mode

StatusMeaning
configuredCreated, exports nothing. Test sends are allowed.
enabledExports mapped events.
disabledSwitched off by you.
errorSet by Kentro when a delivery cannot be sent because of the destination's setup: credentials are missing or cannot be opened, a required config value is missing, the webhook host fails the URL rules when the delivery is sent, or the linked Kentro GO connection cannot be used. Not settable through the API.
  • Enable with PATCH /v1/destinations/:id and { "status": "enabled" }. Enabling requires stored credentials (or a linked Kentro GO connection), otherwise 409 CREDENTIALS_REQUIRED, and at least one enabled mapping, otherwise 409 EVENT_MAPPING_REQUIRED. A meta_capi destination in test mode also needs config.testEventCode, otherwise 400 TEST_EVENT_CODE_REQUIRED.
  • A destination in error receives no new deliveries until you fix the cause and enable it again, which also clears its error text. Deliveries already queued for a destination that is not enabled (in error, or disabled by you) fail with DESTINATION_NOT_ENABLED; a replay after you enable it again puts them back in the queue.
  • A provider rejection, or a delivery that used all 8 attempts, fills the destination's error text and leaves its status as it is. The next delivery that is accepted or sent clears it.
  • PATCH also updates name, propertyId, config, credentials (null clears the stored secret), eventMapping, consentPurpose and testMode. DELETE /v1/destinations/:id removes the destination. Its delivery rows are not deleted with it, but GET /v1/destinations/:id/deliveries answers 404 once the destination is gone, so read the history you need first.
  • testMode starts true; PATCH with { "testMode": false } turns it off. While it is on, an enabled destination delivers only as tests: Meta deliveries carry config.testEventCode and appear only in Events Manager's Test Events, GA4 deliveries go to the validation endpoint and Google Ads uploads run with validateOnly (both record nothing), and webhook requests carry "test": true and an X-Kentro-Test: 1 header.

When Kentro GO is stopped

Kentro GO has a kill switch, and an autonomy level named Emergency disabled. While either one is in force for your workspace, Kentro Pixel sends nothing to any destination. Collection is not affected: events are still accepted and processed.

  • Deliveries wait. New events still create deliveries, and every delivery of the workspace that is queued stays queued, for all four destination types, events and audience membership alike. No attempt is used up. Once the stop is lifted they go out, oldest first.
  • Provider limits still apply to a delivery that waited. Meta takes events up to 7 days old: an older one is recorded rejected, with an error that starts with EVENT_TOO_OLD. GA4 receives an event older than 72 hours without its original time, so GA4 dates it on the day it arrives.
  • Test sends and audience syncs are refused. POST /v1/destinations/:id/test and POST /v1/audiences/:id/sync answer 409 GO_STOPPED (the body is in Limits and errors). An audience sync that was queued before the stop and runs during it is refused too and is not run again: queue it again after the stop.
  • Replays are accepted. POST /v1/destinations/:id/sync answers 202 as usual, and the deliveries it queues wait like the others.
  • A workspace where Kentro GO was never set up is never stopped.

Test sends

POST /v1/destinations/:id/test sends one synthetic event through the real provider API and records the outcome as a delivery row. The synthetic identity is a hashed constant, never a real person.

DestinationWhat the test does
meta_capiSends one event (the first enabled mapping's target, else Lead) with the testEventCode from the body, so it shows only under Test Events. Without { "testEventCode": "..." } the test answers 400 TEST_EVENT_CODE_REQUIRED.
ga4_mpSends one event to the Measurement Protocol validation endpoint and returns its validation messages. The delivery row is sent with validateOnly: true (or rejected).
google_ads_offlineUploads one click conversion with validateOnly: true using an access token from your Kentro GO Google Ads connection.
webhookPOSTs a signed synthetic payload (kentro.pixel.destination_test) with a 5 second timeout; any 2xx answer counts as accepted.
curl -sS https://apis.kentro.live/pixel/v1/destinations/$DESTINATION_ID/test \
  -H "Authorization: Bearer $KENTRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "testEventCode": "TEST12345" }'
{
  "ok": true,
  "status": "accepted",
  "validateOnly": false,
  "deliveryId": "0192f0cb-6f70-7192-a3b4-c5d6e7f8a9b0",
  "destination": "meta_capi",
  "testMode": true,
  "deliveryMode": "test",
  "providerResponse": { "eventsReceived": 1, "messages": [], "fbtraceId": "A1b2C3d4E5f6" },
  "error": null,
  "note": "Provider acceptance means a well-formed test request was accepted. It is not a matched or attributed conversion."
}
ErrorWhen
409 DESTINATION_UNSUPPORTEDThe destination's stored type is not one of the four types above.
409 GO_STOPPEDKentro GO is stopped for the workspace (see "When Kentro GO is stopped").
409 CREDENTIALS_REQUIREDNo stored secret.
400 TEST_EVENT_CODE_REQUIREDMeta test without a test event code.
409 GO_CONNECTION_NOT_FOUNDThe Kentro GO connection does not exist or is disconnected.
409 GO_CONNECTION_NOT_USABLEThe connection cannot issue an access token: reconnect the provider in Kentro GO.
409 GO_CONNECTION_NOT_GOOGLEThe linked Kentro GO connection is not a Google Ads connection, or Kentro GO did not say which provider it belongs to. Its token is not sent to Google: link a Google Ads connection.
502 GO_PROVIDER_UNAVAILABLE, 502 GO_API_ERRORGoogle could not refresh the access token right now, or the Kentro GO call failed.
503 GO_API_UNAVAILABLEGoogle Ads sending through Kentro GO is not configured on this environment.
422 WEBHOOK_TARGET_NOT_ALLOWEDThe webhook URL fails the rules below.
503 CREDENTIALS_UNAVAILABLEStored credentials cannot be opened.

None of these answers sends anything or records a delivery row. A provider that refuses the test event, or cannot be reached, is a different case: the answer is 200 with "ok": false, "status": "rejected", the provider's answer in providerResponse and the reason in error, and the delivery row is recorded.

Google Ads offline conversions

  • Set credentialSource: "go_connection" and the connection's id in goConnectionId (connections are listed by GET https://apis.kentro.live/go/v1/connections). No Google Ads developer token is needed: Kentro sends conversions with the OAuth access token of your connection and never stores Google tokens on the destination.
  • conversionAction is the resource name of an upload-type conversion action; loginCustomerId is the manager account id when the connection signs in through one.
  • Mapped conversions are uploaded as click conversions and need a Google click id (gclid, gbraid or wbraid) captured on a visit with marketing consent; without one the delivery is suppressed (no_click_id).
  • Refunds and cancellations are sent as adjustments: a retraction for a cancellation or a full refund, a restatement of the remaining value for a partial refund. The consent signals on each upload (adUserData, adPersonalization) come from the person's consent record.

Webhooks

Webhook URLs must use https:// and a public host name: no IP literals, localhost, .local or .internal names, no credentials and no fragment. At send time every address the host resolves to must be public, and redirects are not followed. Live deliveries time out after 10 seconds (test sends after 5). A 2xx answer counts as accepted; 408, 429, 5xx and network errors are retried; any other answer is recorded as rejected. Kentro reads at most the first 4 KB of your response.

HeaderValue
Content-Typeapplication/json
User-AgentKentro-Pixel-Webhook/1.0
X-Kentro-Eventkentro.pixel.event, kentro.pixel.audience_membership or kentro.pixel.destination_test
X-Kentro-DeliveryLive deliveries: the delivery id, the same on every retry (use it to drop repeats)
X-Kentro-TestLive deliveries of a destination in test mode: 1
X-Kentro-TimestampUnix time in seconds
X-Kentro-Signaturesha256= followed by the hex HMAC-SHA256 of timestamp + "." + rawBody, keyed with your signingSecret

Payload types:

  • kentro.pixel.event (one mapped event): type, id (the delivery id), created_at, destination_id, test, targets (the targets of every enabled mapping entry the event matched, in eventMapping order), event and, when the matched entry has fields, data. event carries event_id, event_name, occurred_at, received_at, source_type, authoritative, refs, context (page_path, referrer_domain, utm, device_class), the effective consent and properties.
  • data holds one value per name in fields, read from a dotted path of event: { "order": "refs.order_ref", "total": "properties.total.amount_minor" } sends "data": { "order": "order-1001", "total": 4999 }. A path that does not exist gives null. A path steps through objects only: it does not index into a list (properties.items.0.sku gives null), and a path that ends on a list or an object returns it whole. When several enabled entries match the event, data follows the fields of the first of them in eventMapping order.
  • kentro.pixel.audience_membership (one page of an audience sync): type, id, created_at, destination_id, test, audience (id, name), mode, window (from, to), page, page_size, and joined and left lists of { "subject_id", "subject_type", "subject_key" }; a leave caused by a privacy deletion carries "deleted": true.
  • kentro.pixel.destination_test (a test send):
{
  "type": "kentro.pixel.destination_test",
  "id": "0192f0cb-6f70-7192-a3b4-c5d6e7f8a9b0",
  "created_at": "2026-10-09T18:20:00.000Z",
  "destination_id": "0192f0ca-5e6f-7081-9293-a4b5c6d7e8f9",
  "test": true,
  "event": { "event_name": "kentro.test", "event_id": "kentro_test_0192f0cb-6f70-7192-a3b4-c5d6e7f8a9b0", "occurred_at": "2026-10-09T18:20:00.000Z", "properties": { "synthetic": true } }
}

Verify the signature over the raw request bytes before parsing the JSON, and reject timestamps outside a window you choose (Kentro uses 300 seconds for its own signatures):

const crypto = require('node:crypto');
const http = require('node:http');

const SIGNING_SECRET = process.env.KENTRO_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;

function verifyKentroSignature(rawBody, headers, secret) {
  const timestamp = headers['x-kentro-timestamp'];
  const signature = headers['x-kentro-signature'] || '';
  if (!/^\d+$/.test(timestamp || '')) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex');
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

http.createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const rawBody = Buffer.concat(chunks);
    if (!verifyKentroSignature(rawBody, req.headers, SIGNING_SECRET)) {
      res.writeHead(401).end();
      return;
    }
    const payload = JSON.parse(rawBody.toString('utf8'));
    console.log('Kentro webhook', req.headers['x-kentro-event'], payload.id);
    res.writeHead(204).end();
  });
}).listen(8080);

Audience membership

POST /v1/audiences/:id/sync queues a sync of an active audience to destinations and answers 202 with a jobId. Which destination types take membership:

destinationAudience membership
webhookYes: signed kentro.pixel.audience_membership pages, as described in "Webhooks".
meta_capiYes, as a Meta Custom Audience in the ad account linked on the destination (config.adAccountId with config.goConnectionId). Not while the destination is in test mode: Meta audience uploads have no test mode.
google_ads_offlineNo: Google Ads audience uploads (Customer Match) are not available.
ga4_mpNo: GA4 receives conversion events only.

Every destination reports audienceSync: true when its type takes audience membership. It describes the type, not the setup: a Meta destination without a linked ad account reports true and its sync is still refused.

  • The destination's consentPurpose must equal the audience's, and Meta takes only audiences built on marketing consent.
  • Without destinationIds in the body, the sync goes to every enabled destination that passes these rules.
  • A sync sends who joined and who left since the previous sync of the audience to that destination. It sends the full current membership instead when no page of an earlier sync is still waiting, sent or accepted in the destination's delivery history (kept 30 days): the first sync, and a sync after earlier ones that all failed, were refused or suppressed, or are older than 30 days. It also does when the Meta Custom Audience is not the one the previous sync used, for example a newly created one, and on the first sync after a webhook leaves test mode: pages sent in test mode carry X-Kentro-Test, and a receiver that discards them still gets every member. While the destination stays in test mode, its syncs build on its test pages. A page holds up to 1,000 members.
  • Meta receives hashed email addresses and phone numbers, never a raw value. A page in which no member has one is recorded suppressed with no_match_identifiers.

A sync that cannot go ahead answers 404 for an unknown audience or destination, and otherwise 409:

ErrorWhen
GO_STOPPEDKentro GO is stopped for the workspace (see "When Kentro GO is stopped").
AUDIENCE_NOT_ACTIVEThe audience is not active.
DESTINATION_NOT_ENABLEDA named destination is not enabled.
DESTINATION_CAPABILITYA named destination's type takes no audience membership: GA4 or Google Ads.
CONSENT_PURPOSE_MISMATCHA named destination's consentPurpose differs from the audience's.
AD_NETWORK_REQUIRES_MARKETING_AUDIENCEA Meta destination, and an audience that is not built on marketing consent.
META_AD_ACCOUNT_REQUIREDA Meta destination without a linked ad account.
META_AUDIENCE_TEST_MODEA Meta destination in test mode.
NO_ELIGIBLE_DESTINATIONSThe body named no destination, and no enabled destination passes the rules.

A refusal about destinations lists them in destinationIds.

Deliveries and what accepted means

GET /v1/destinations/:id/deliveries?status&limit&cursor lists delivery rows, newest first, as { "items": [...], "nextCursor": ... }. Each row carries id, destinationId, journalId, conversionId, dedupeKey, status, testMode, validateOnly, attempts, requestRedacted, response, providerReceipt, suppressedReason, sentAt, nextAttemptAt, error and createdAt. The requestRedacted of an event delivery names the mapping entries the event matched: targets, and mapping with each entry's source, target, fields and enabled.

StatusMeaning
queuedWaiting to be sent.
sentThe request left Kentro, but the provider does not confirm acceptance: GA4 and validate-only test calls.
acceptedThe provider accepted the request.
rejectedThe provider refused it; see error and response.
failedKentro could not complete the delivery; see error.
suppressedKentro deliberately did not send it. suppressedReason: consent_not_granted, gpc_opt_out, strict_privacy_mode, quarantined, sensitive_event, no_click_id, no_client_id, no_match_identifiers (an audience page for Meta in which no member has a hashed email or phone), audience_deleted (an audience page whose audience was deleted before it was sent; the destination is not affected), privacy_request or consent_withdrawn.

accepted means the provider accepted a well-formed request. It does not mean the provider matched the event to a person, counted a conversion or attributed it to a campaign; test events never appear in live reports.

A delivery waiting while Kentro GO is stopped stays queued: no status or field marks it as held. After a delete or anonymize privacy request, the response of the deliveries of that person's events is { "erased": true, "reason": "privacy_request" } (see Consent and privacy).

Replays

POST /v1/destinations/:id/sync with an optional { "from", "to" } window queues a replay of the window's events for an enabled destination and answers 202 with a jobId.

  • Default window: the last 7 days. YYYY-MM-DD values are whole UTC days with an inclusive end; ISO timestamps are taken as they are.
  • A replay queues a delivery for every accepted event of the window that the destination maps and that has no delivery yet, and puts failed deliveries of those events back in the queue. An event that already has a delivery in another status is left alone, so nothing is delivered twice.
  • A replay reaches back 30 days. It recognizes the events it already delivered by their delivery history, which is kept for 30 days, so a window that starts earlier answers 400:
{ "error": "REPLAY_RANGE_TOO_OLD", "message": "A replay covers the last 30 days. Choose a start date on or after Oct 22, 2026." }
  • The day in message is the first whole UTC day inside the 30 days at the moment of the request, written like Oct 22, 2026. A window without from starts 7 days before its to, so an old to alone is refused the same way. Match on error, not on the sentence: its wording changed on 2026-11-20.
  • A window longer than 180 days answers 400 RANGE_TOO_LARGE. A date that cannot be read, or a from that is not before to, answers 400 INVALID_RANGE.
  • A destination that is not enabled answers 409 DESTINATION_NOT_ENABLED with the message Destinations export nothing until someone with permission to manage Kentro Pixel enables them.
  • While Kentro GO is stopped, a replay is accepted and its deliveries wait (see "When Kentro GO is stopped").