OutboundAPI connection

Have an orchestration flow call an HTTP endpoint in your system or a third-party platform when a customer event occurs.

The OutboundAPI block lets a Lobyco orchestration flow call an HTTP endpoint in your system — or any third-party platform such as Salesforce, Bloomreach, Iterable, or Adobe — whenever a customer event occurs. Use it to sync loyalty events into your CRM, trigger journeys in an external marketing platform, or notify your own backend in real time.

This guide describes the technical contract: how the request is built, how authentication works, what your endpoint must do, and the platform’s retry, timeout, and security behavior.

Availability: the OutboundAPI block is enabled per environment. Contact your Lobyco representative if you don’t see it in the orchestration canvas.

The inbound counterpart is the InboundAPI integration. For the payload schemas Lobyco sends, see Events.

When the block fires

The OutboundAPI block runs each time a customer reaches it in an orchestration flow. It must sit downstream of an event block — that event supplies the data the block sends. The flow itself can be segmentation-based or event-driven (for example Segment → Challenge → [event] → OutboundAPI); the only requirement is that an event block comes somewhere before the OutboundAPI block.

The triggering event can be any of a growing set of platform and activity events — currently including customer sign-up, game won / lost, challenge completed, and offer assigned. More event types are added over time, so treat this as a non-exhaustive list.

One event for one customer produces one HTTP request. A failed request affects only that customer’s journey — other customers in the flow continue normally.

The call is one-way: the response from your endpoint is recorded for troubleshooting but does not change the orchestration flow.

How it works

A marketer (or you, as an integrator) places the OutboundAPI block in an orchestration flow on the visual canvas, downstream of an event block. Each time a customer passes through the block, the platform:

1. Takes the event data

   Takes the event data produced by the upstream event block (for example a sign-up or purchase event).

2. Enriches the data

   Enriches the data with the full customer profile and/or purchase details — but only if your templates reference them (see Dynamic values).

3. Renders the request

   Renders the URL, header values, and body, replacing all placeholders with real data.

4. Authenticates

   Authenticates — obtains an OAuth2 Bearer token, builds a Basic Auth header, or attaches your custom headers.

5. Sends the request

   Sends the HTTP request to your endpoint.

6. Records the outcome

   Records the outcome (status code, response body, response time) in the run details.

If any of the enrichment, rendering, or authentication steps fails — missing data, an unresolvable placeholder, a failed token request — the block fails without calling your endpoint.

Simulation runs are real. When an orchestration flow is run in simulation mode, the OutboundAPI block still sends the HTTP request. Point test flows at a test endpoint.

Configuration reference

Setting	Required	Description
URL	Yes	Absolute URL of the endpoint to call. May contain placeholders (e.g. https://api.example.com/contacts/{{ member.id }}). Must not resolve to a private network address.
HTTP method	Yes	One of GET, POST, PUT, DELETE, PATCH.
Headers	No	Key–value pairs added to the request. Values may contain placeholders.
Body	No	A JSON body template; may contain placeholders. Available for POST, PUT, and PATCH. Always sent with Content-Type: application/json; charset=utf-8 — the content type is fixed, and a Content-Type entry among custom headers is ignored. The configuration UI requires the body to be valid JSON.
Authentication	No	Either a saved Integration (recommended) or an inline auth configuration. You cannot set both at once.

The configuration is validated when the flow is saved: the URL and method are checked, an inline auth config must be complete, and a referenced integration must exist and not be deleted.

Testing the block

The block’s configuration dialog has a Test button that sends a single real request with the current configuration — including authentication — and shows the response status code, response time, and response body. Use it to confirm credentials and payload format with your endpoint before publishing the flow, and prefer a test endpoint or pre-production environment while doing so.

Dynamic values (placeholders)

URL, header values, and the body are Liquid templates. Placeholders use double curly braces:

{{ source.property }}

Data sources

The placeholder namespace for a customer is called member, as are the API and the memberId field behind it.

Source	Where it comes from	Requirement
event	The payload of the event that triggered the flow. Fields depend on the event type (e.g. {{ event.memberId }}, {{ event.storeId }}).	Always available.
member	The full customer profile, fetched from the Lobyco Member API at execution time. Includes metadata — useful for IDs your system already knows, e.g. {{ member.metadata.externalContactId }}.	The event payload must contain memberId.
purchase	The purchase/receipt details, fetched from the Lobyco Purchase API at execution time.	The event payload must contain completedByPurchaseId — currently only the Challenge completed event provides it.

Enrichment is automatic and on-demand: the platform scans your templates and only calls the Member or Purchase API when a template actually references member. or purchase.. If the required ID is missing from the event, or the lookup returns no data, the block fails and no request is sent.

Tip: in the configuration dialog, type two opening braces to open an autocomplete dropdown of the placeholders available for your flow’s event type, including nested values (e.g. purchase.products[0].name).

Example body

{
    "receiptId": "{{ purchase.receiptId }}",
    "totalAmount": {{ purchase.totalAmount }},
    "storeId": "{{ purchase.storeId }}",
    "memberEmail": "{{ member.email }}"
}

Supported Liquid features

Feature	Example
Property access, nested	{{ event.user.profile.name }}
Array indexing	{{ event.items[0] }}
Standard filters	{{ event.name | upcase }}, {{ event.items | size }}

Conditionals and loops are supported too:

{% if event.amount > 100 %}high value{% else %}standard{% endif %}

{% for item in event.items %}{{ item.name }}{% endfor %}

Loops are capped at 10,000 iterations.

In addition to standard Liquid filters, these filters are available:

Filter	Example	Result
at_least	{{ event.amount | at_least: 0 }}	Lower-bounds a number.
at_most	{{ event.amount | at_most: 100 }}	Upper-bounds a number.
url_encode	{{ event.query | url_encode }}	Percent-encodes a string for safe use in URLs.
url_decode	{{ event.encoded | url_decode }}	Decodes a percent-encoded string.
sort_natural	{{ event.tags | sort_natural }}	Case-insensitive sort of a list.
date	{{ ‘now’ | date: ‘%Y-%m-%dT%H:%M:%S’ }}	Formats a date using strftime patterns. Accepts date values, date strings, ‘now’, and ‘today’ (UTC).

Authentication

Three authentication types are supported. Credentials can be stored once as a reusable Integration in the Lobyco Admin Portal and referenced from any number of flows — this is the recommended approach. Integration secrets are encrypted at rest (AES-256-GCM), always masked in the UI and API responses, and can be rotated in one place. The Admin Portal also offers a test action that performs a real call with the configured credentials.

OAuth2 Client Credentials

For platforms that issue short-lived Bearer tokens (e.g. Salesforce).

Field	Required	Description
Token URL	Yes	The token endpoint. Must be publicly reachable (private addresses are rejected).
Client ID / Client Secret	Yes	Your OAuth2 client credentials.
Scopes	No	Requested scopes, sent space-separated in the token request.
Additional headers / body parameters / query parameters	No	Extra values some providers require on the token request.

Token request behavior — your identity provider receives:

POST {tokenUrl}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...&scope=...

and must return JSON containing access_token (required) and expires_in (in seconds). The platform then calls your endpoint with Authorization: Bearer {access_token}.

Tokens are cached for 90% of expires_in and reused across executions with the same credentials, so your token endpoint is not called on every event. If expires_in is missing or zero, the token is not cached and is requested per call.

Basic Auth

For platforms authenticating with username/password or key/secret pairs (e.g. Bloomreach private API groups). The platform base64-encodes username:password and sends Authorization: Basic {encoded} on every request.

Custom Headers

For platforms using static API-key headers (e.g. Iterable Api-Key, Adobe X-Api-Key). Configure one or more headers; mark sensitive values as secret so they are encrypted and masked. All configured headers are attached to every request.

What your endpoint must do

• Respond within 5 seconds. The per-attempt timeout is 5 seconds by default (configurable per environment). Accept the request, respond, and process asynchronously if your handling is slow.
• Return a 2xx status for success. Any 2xx counts as success; everything else marks the block execution as failed. Redirects are followed by standard HTTP client behavior; auth headers are set on the initial request.
• Be idempotent. Failed attempts are retried (see below), so the same event can reach your endpoint more than once. The platform does not send an idempotency key today — deduplicate using an identifier from the event payload (e.g. a receipt or activity ID).
• Expect UTF-8 JSON when a body is configured (Content-Type: application/json; charset=utf-8).

Retries and timeouts

Parameter	Default
Timeout per attempt	5,000 ms
Retries	2 (up to 3 attempts total)
Backoff	Jittered exponential, ~100 ms base delay

Retries trigger on transient failures only: HTTP 5xx, HTTP 408, network errors, and timeouts. Other non-success statuses (e.g. 400, 401, 404) are not retried and fail the block immediately. The same retry policy applies to OAuth2 token requests.

Defaults can be tuned per environment by Lobyco.

What is recorded

For every execution, the platform records the response status code, response body, and response time in the run details. This data is visible to flow operators for troubleshooting, so avoid returning sensitive data in your response body.

Security and restrictions

• Private networks are blocked. The target URL — and the OAuth2 token URL — must not resolve (directly or via DNS) to a private or link-local address (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, plus Lobyco-internal ranges). This is enforced both when the flow is saved and again at execution time, after placeholders are resolved.
• Allowed methods are limited to GET, POST, PUT, DELETE, PATCH.
• Body content type is always application/json; charset=utf-8. Other formats (form-urlencoded, XML, multipart) cannot be configured, and a Content-Type custom header is silently ignored.
• Secrets (OAuth2 client secrets, Basic Auth passwords, secret custom headers) are encrypted at rest and never returned in plaintext by any Lobyco API or UI.

Example setups

Salesforce (OAuth2 Client Credentials)

1. Create a Connected App

   In Salesforce, create a Connected App with the client-credentials flow enabled and note the consumer key/secret.

2. Create an Integration

   In the Lobyco Admin Portal, create an Integration of type OAuth2 Client Credentials with Token URL https://{your-domain}.my.salesforce.com/services/oauth2/token, the consumer key as Client ID, and the consumer secret as Client Secret.

3. Configure the OutboundAPI block

   In the OutboundAPI block, reference the integration and configure the target REST endpoint, e.g. POST https://{your-domain}.my.salesforce.com/services/data/v60.0/sobjects/Lead/ with a JSON body built from event and member placeholders.

Bloomreach Engagement (Basic Auth)

1. Create a Private API group

   In Bloomreach, open Project Settings → Access Management → API → API Groups and create a Private API group with the permissions your flow needs. Copy the API Key ID and API Secret.

2. Create a Basic Auth Integration

   Create a Basic Auth Integration: Username = API Key ID, Password = API Secret.

3. Configure the endpoint

   Point the block at the desired endpoint, e.g. POST https://api.exponea.com/track/v2/projects/{projectToken}/customers/events.

Public-token endpoints (/track/v2/..., consent fetch) alternatively work with a Custom Headers Integration carrying Authorization: Token <api_token> (marked secret). Private endpoints (/data/v2/..., /api/v2/...) require Basic Auth — default to Basic Auth if your flow touches anything beyond tracking.

API-key platforms (Custom Headers)

For Iterable, Adobe, or your own webhook receiver: create a Custom Headers Integration with the vendor’s key header (Api-Key, X-Api-Key, etc.), mark the value as secret, and reference it from the block.