Custom API endpoint

Overview

The Custom API endpoint pushes your mapped records to any HTTP API you define. You choose the method (POST, PUT or PATCH), the destination URL (with {{field}} tokens), the headers, the authentication and optional request signing — and the connector delivers each changed record to it on the pipeline's schedule.

It is the generic, push sibling of the Webhook connector, and the mirror image of the Managed data feed: where the Managed data feed lets another system pull from us, the Custom API endpoint lets us push to a system you run.

Is this right for you?

Choose the Custom API endpoint when:

• The receiving system exposes an HTTP endpoint you control (or can stand one up) — a SaaS or ERP API, an app's ingest route, or an ingestion endpoint in front of a data lake or warehouse.
• You want changes pushed as they sync (near-real-time, per record), rather than waiting for the other side to poll.
• You need control over the exact method, URL shape, authentication and signing the receiver expects.

Prefer the Managed data feed (pull) instead when:

• You would rather not run an always-on endpoint — let the other system pull on its own schedule.
• You are feeding a data lake or warehouse that already ingests by pulling a REST source — see Consuming a Managed data feed.
• The catalogue is large — a pull hands over the whole changed set at once, whereas Custom API sends one request per record (bulk batching is on the roadmap).

How it works

1. You build a pipeline: WFX in, Custom API endpoint out, and map the fields you want to send.
2. You configure the destination — method, URL, authentication, optional HMAC signing — on the connection (the fields are in the reference below).
3. On each sync the connector sends one request per changed record to your endpoint. Failed deliveries retry automatically with increasing backoff, and every attempt (request and response) is captured in the run's audit.

Before going live, use Send test request on the connection to fire a sample at your endpoint and see the real status and response — with your secrets redacted from the echo.

What your endpoint receives

For each record:

• Method — the POST, PUT or PATCH you chose.
• URL — your HTTPS URL with any {{field}} tokens filled in from that record (URL-encoded). If a token cannot be resolved the record fails closed — it is never sent to a blanked URL.
• Headers — always Content-Type: application/json; plus any custom headers you set; plus your chosen authentication (a Bearer or Basic Authorization header, a custom API-key header, or an ?api_key= query parameter).
• Body — the mapped record as a single JSON object, sent verbatim — no wrapper or envelope. The shape is exactly what your field mapping produces.
• Signature (optional) — with signing on, an X-Signature header (or a name you choose) of the form t={unix_timestamp},v1={hex_hmac}. The signature is an HMAC (SHA-256 or SHA-512) of the string {timestamp}.{raw_body} — the timestamp, a literal dot, then the exact bytes of the request body — keyed with your shared secret. Verify against the raw received bytes, not a re-serialized copy.

Your endpoint should:

• Return HTTP 2xx to acknowledge (unless you enable "treat any response as success"), within about 30 seconds.
• Be reachable over HTTPS on port 443 — plain HTTP and private or internal addresses are refused for safety.
• Treat delivery as at-least-once and de-duplicate on the record's business key — a retried record is re-sent.

FAQ

Is it real-time? Near — records are pushed on each pipeline run as they change, one request each. For very large catalogues the Managed data feed (pull) is more efficient, because it hands over the whole changed set at once.

What if my endpoint is down? Failed deliveries retry automatically with increasing backoff (minutes, up to hours) and then stop; every attempt and response is visible in the run's audit.

Can you sign requests so I know they are genuinely from you? Yes — turn on HMAC signing and share a secret, then verify the X-Signature header as described above.

Can I restrict where you are allowed to send? Your workspace can keep an approved-destinations list; when set, deliveries only go to those domains.

How do I test before going live? Use Send test request on the connection — it sends a sample to your real endpoint and shows the status and response, with secrets redacted.