Skip to main content

In your app

A controller answers a route on your app: it calls createExternalConversionEvent() and returns the answer.

Add the controller

app/Http/Controllers/CreateExternalConversionEventController.php
The other values are the example’s: take yours from the request, a form or your database.

Add the route

routes/web.php
It acts with your key’s access, so auth lets only your signed-in users reach it.

Call it

Your own page’s form or script sends POST /conversion-event/external (a form adds @csrf, as every web route checks it), and gets back its answer as JSON. Test it, below, calls it.
To keep the call in an Action instead, this writes app/Actions/Attract/CreateExternalConversionEvent.php (an invokable Action that calls createExternalConversionEvent()) and its test under tests/Feature/Actions/Attract/ (Pest when your app has it):
Terminal

Call it from the terminal

Terminal
It calls createExternalConversionEvent() on your default site and prints its answer as JSON. It writes, so it asks first: add --force to skip the question in a script. See Call any method from the terminal for every argument type. Google Analytics only accepts it within 72 hours of when it happened. Joining. The CMS joins the fact to a visitor’s journey with match, strongest first (visitor ID, the fk_at token, _gcl_au, a click ID, hashed email / phone), and copies that visitor’s attribution onto the event. join.by in the answer says which matched. The producer’s own click IDs win over the visitor record’s; its browser IDs only fill gaps. Consent. The producer’s consent flags govern what is sent about the fact (omitted flags are granted). A denial trims what is sent — no contact details or browser data, Google receives CONSENT_DENIED — but the conversion is always stored and delivered. Browser context. Send the customer’s client (IP, user agent) and page.url as captured when they booked; with them the fact reaches Meta as a website event (de-duplicated against the pixel), without them as system_generated. Idempotent on eventId. Posting the same fact again returns the stored event with created: false; the same ID with different content is a 409. Retry freely. Signed: every API key must sign this request (X-Fetchski-Timestamp + X-Fetchski-Signature, see the headers below), whatever its own signing mode. Signed-in users in the CMS need no signature. Signing requests shows how, from the API and both SDKs.

Required parameters

Named arguments, e.g. createExternalConversionEvent(eventId: …); leave out the optional ones.
string
required
Required. Opaque, unique per site, stable. The CMS mints a UUID for events it originates; another system mints its own (e.g. tenant-42:order:1234:purchase). Forwarded unchanged to every ad platform as its de-duplication key. Matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$. At most 128 characters.
string
required
Required. A Conversion’s id or key (GET /conversion/definitions); it must have a “Reported by another system” trigger. At most 128 characters.
ExternalConversionFactProducer|array<string, mixed>
required
Required. Your system: who is posting the fact.
\DateTimeInterface|string|null
Optional. When it happened (not in the future). Defaults to now. Format: an ISO 8601 date and time.
?float
Optional. Rounded to cents. Defaults to the Conversion’s value. At least 0.
?string
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. ISO 4217 code of value, e.g. USD. Matches ^[A-Z]{3}$.
FactMatch|array<string, mixed>|null
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. What the CMS may join the fact to a visitor with, tried strongest first: visitorId, token (fk_at), gclAu, a click ID, then emailSha256 / phoneSha256. Hashes also travel with the conversion to the platforms (see UserDataHashes for the normalization).
FactConsent|array<string, mixed>|null
Optional. The customer’s ad-data consent as the producer knows it. Each flag defaults to the US-friendly value when omitted. A denial trims what is sent (no contact details or browser data; Google receives CONSENT_DENIED); the conversion itself is always stored and delivered.
FactClient|array<string, mixed>|null
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. The customer’s browser as captured WHEN THEY BOOKED (not the server confirming later). With a user agent and a page URL the fact reaches Meta as a website event; without, as system_generated. Kept only until delivery is finished, never returned.
ExternalConversionFactPage|array<string, mixed>|null
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Where the customer was when it happened.
A CreateExternalConversionEventResponse (Fetchski\AttractCmsLaravel\Data\CreateExternalConversionEventResponse). The stored event. created is false when this event ID was already stored with the same content. Read its properties ($createExternalConversionEvent->created): each says whether the site always sends it.
bool
Always sent.
ConversionEvent
Always sent. A ConversionEvent. One conversion occurrence. Fields the visitor’s consent did not allow are ABSENT, not empty. Never returned: the visitor’s IP address and user agent, outbox lease and retry bookkeeping.
Nothing to catch: the SDK retries what is safe, and Laravel logs and renders the rest (see Errors and testing).
400
The request is not valid. data.errors lists each problem with the path of the parameter or body field it concerns.Retried first: No. Read: errors() (field → messages), siteMessage().
401
The API key is missing, malformed, unknown, disabled, expired or archived (invalid), or a request that must be signed — by the route, or by the key’s own signing mode — has a missing, stale or wrong signature (an upload signs its SHA-256, declared in X-Fetchski-Content-SHA256, in the body’s place) (unauthorized).Retried first: No. Read: siteMessage(), errorName(), data().
403
The API key lacks the scope this route needs (the message names it), or the key is used from an address outside its allowlist.Retried first: No. Read: siteMessage(), errorName(), data().
404
Nothing with this identifier — or the caller may not use the Data API at all (anonymous visitors and non-admin sessions get 404 so the API is not advertised). A write while conversion tracking is switched off also answers 404.Retried first: No. Read: siteMessage(), errorName(), data().
409
The identifier was already used with different content (an event ID re-posted with a changed fact, an adjustment ID re-used), or the event is retracted.Retried first: No. Read: siteMessage(), errorName(), data().
429
The key used up its reads- or writes-per-minute limit (set per key; defaults 600 / 120). Still, after the client’s own waits and retries.Retried first: Yes: the client waits Retry-After (1 s when absent; over 60 s it gives up at once) and retries, up to retries times (2 by default). Read: retryAfter() (seconds, or null), siteMessage().
5xx
The site failed (or something in front of it did). Its logs say why.Retried first: No: a write may have landed. Read: siteMessage(), errorName(), data().
no answer
No answer: DNS, a refused connection, TLS, or the timeout (15 s per attempt by default).Retried first: Only when nothing reached the site (neverConnected()); never after a timeout, when it may have landed. Read: reason(), neverConnected().
not sent
The client refused to send it (e.g. a path segment of ..); the site never saw it.Retried first: No. Read: reason() (what to change).
any other
Any other status, or a success whose JSON doesn’t match this SDK version’s types (update the SDK).Retried first: No. Read: reason(), status().
setup
Attract::site('acme') named a slug that isn’t under sites in config/fetchski-attract.php.Retried first: No: nothing was sent. Read: getMessage(), $e->slug.
setup
The site’s config entry is wrong: no url, a malformed api_key, a key filed under another slug, or no default site.Retried first: No: nothing was sent. Read: getMessage() (what to fix).

Behavior

  • Access: an API key with conversions:write — or its group master ads:all, or admin:all — or a signed-in user holding the conversion-events:write permission. Anonymous callers get 404.
  • Rate limit: the key’s own writes-per-minute limit, set when the key is created (default 120); over it, 429 with Retry-After. The client waits and retries for you; you see RateLimited only if that runs out.
  • Retries: a write is sent again only after a 429 (refused before it acted) or when it never reached the site. After a timeout or a 5xx it may have landed: check before you send it again.
  • Timeout: 15 s per attempt by default; raise timeout in config/fetchski-attract.php for longer.

Test it

It calls the route above with the SDK faked: the fake answers every call with a valid example, so nothing leaves your machine and no config or key is needed. Save it as tests/Feature/CreateExternalConversionEventTest.php, then run your tests:
tests/Feature/CreateExternalConversionEventTest.php
Terminal
Answer with your own values: fake conversionEvents.createExternalConversionEvent with CreateExternalConversionEventResponse::factory()->make([...]), the fields you give over a valid example (nested ones too).
tests/Feature/CreateExternalConversionEventAnswerTest.php

List conversion events (incremental sync)

Attract::conversionEvents()->listConversionEvents()

Get one conversion event

Attract::conversionEvents()->getConversionEvent()

Retract or restate a conversion event

Attract::conversionEvents()->adjustConversionEvent()

POST /conversion-event/external

The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.