OutboundAPI connection - Lobyco Help center

The Outbound API block lets a Lobyco orchestration flow call an HTTP endpoint when a customer event occurs. The endpoint can be in your own system or in a platform such as Salesforce, Bloomreach, Iterable or Adobe. Use it to sync loyalty events into your CRM, start a journey in a marketing platform, or notify your own backend. This page is the technical contract. It covers how the request is built and authenticated, what your endpoint must do, and how Lobyco retries and secures the call. The marketer’s side is on Block reference.

The Outbound API block is enabled per environment. If the marketer does not see it in the orchestration canvas, contact your Lobyco representative.

At a glance

Topic	What it decides
When the block fires	Which events trigger a call, and what one call covers
How a request is built	The six things Lobyco does before your endpoint sees anything
Configuration	The URL, method, headers, body and authentication the block holds
Placeholders	The Liquid templates and the data they can reach
Authentication	OAuth2 client credentials, basic auth or custom headers
What your endpoint must do	Timeout, status codes, idempotency and content type
Retries and timeouts	How many attempts Lobyco makes, and for which failures
Security and restrictions	Blocked addresses, allowed methods, fixed content type, secrets
Example setups	Salesforce, Bloomreach and API-key platforms

When the block fires

The block runs each time a customer reaches it in a flow. It must sit downstream of an event block, because 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 it. The triggering event can be any of a growing set of platform and activity events. Today that includes customer sign-up, game won, game lost, challenge completed and offer assigned. Lobyco adds event types over time, so treat the list as open. One event for one customer produces one HTTP request. A failed request affects only that customer’s journey; other customers in the flow continue. The call is one-way. Lobyco records your endpoint’s response for troubleshooting, but the response does not change the flow.

How a request is built

Each time a customer passes through the block, Lobyco:

Takes the event data produced by the upstream event block, for example a sign-up or a purchase event.
Enriches it with the full customer profile, the purchase details, or both, but only if your templates reference them. See Placeholders.
Renders the URL, the header values and the body, replacing every placeholder with real data.
Authenticates: obtains an OAuth2 bearer token, builds a basic auth header, or attaches your custom headers.
Sends the HTTP request to your endpoint.
Records the outcome in the run details: status code, response body and response time.

If enrichment, rendering or authentication fails, the block fails without calling your endpoint. That covers missing data, a placeholder that cannot be resolved, and a failed token request.

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

Configuration

Setting	Required	What it holds
URL	Yes	The absolute URL to call. It can contain placeholders, for example `https://api.example.com/contacts/{{ member.id }}`. It must not resolve to a private network address.
HTTP method	Yes	One of `GET`, `POST`, `PUT`, `DELETE` or `PATCH`.
Headers	No	Key and value pairs added to the request. Values can contain placeholders.
Body	No	A JSON body template, available for `POST`, `PUT` and `PATCH`. It can contain placeholders. The content type is always `application/json; charset=utf-8`, and a `Content-Type` entry among the custom headers is ignored. The body must be valid JSON.
Authentication	No	A saved integration, which Lobyco recommends, or an inline authentication configuration. Not both.

Lobyco validates the configuration when the flow is saved. The URL and the method are checked, an inline authentication 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. It sends one real request with the current configuration, authentication included, and shows the status code, the response time and the response body. Use it to confirm credentials and payload shape before publishing the flow, against a test endpoint or a pre-production environment.

Placeholders

The URL, the header values and the body are Liquid templates. A placeholder is a property in double curly braces:

{{ source.property }}

Data sources

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

Source	Where it comes from	Requirement
`event`	The payload of the event that triggered the flow. The fields depend on the event type, for example {{ event.memberId }} or {{ event.storeId }}.	Always available.
`member`	The customer’s full profile, fetched from the Members API at execution time. It includes `metadata`, useful for ids your system already knows, such as {{ member.metadata.externalContactId }}.	The event payload must contain `memberId`.
`purchase`	The purchase details, fetched from the Purchase API at execution time.	The event payload must contain `completedByPurchaseId`. Today only the challenge completed event provides it.

Enrichment is automatic and on demand. Lobyco scans your templates and calls the Members API or the Purchase API only when a template 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.

In the configuration dialog, type two opening braces to open an autocomplete list of the placeholders for your flow’s event type. Nested values are included, such as 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 work too. Loops are capped at 10,000 iterations.

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

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

Beside the 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 with strftime patterns. Accepts date values, date strings, ‘now’ and ‘today’ (UTC).

Authentication

Three authentication types are supported. Store the credentials once as an Integration in the Lobyco Admin Portal and reference it from any number of flows. Lobyco recommends this over inline credentials. Integration secrets are encrypted at rest with AES-256-GCM, always masked in the UI and in API responses, and rotated in one place. The admin portal also has a Test action that makes a real call with the configured credentials.

OAuth2 client credentials

For platforms that issue short-lived bearer tokens, such as Salesforce.

Field	Required	What it holds
Token URL	Yes	The token endpoint. It must be publicly reachable; private addresses are rejected.
Client ID and client secret	Yes	Your OAuth2 client credentials.
Scopes	No	Requested scopes, sent space-separated in the token request.
Additional headers, body parameters or query parameters	No	Extra values some providers require on the token request.

Your identity provider receives this token request:

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

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

It must return JSON with access_token and expires_in, in seconds. Lobyco 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 that authenticate with a username and password, or a key and secret pair, such as Bloomreach private API groups. Lobyco base64-encodes username:password and sends Authorization: Basic {encoded} on every request.

Custom headers

For platforms that use a static API-key header, such as Iterable’s Api-Key or Adobe’s X-Api-Key. Configure one or more headers, and mark sensitive values as secret so they are encrypted and masked. Every configured header is attached to every request.

What your endpoint must do

Respond within 5 seconds. The timeout per attempt is 5 seconds by default; Lobyco can change it per environment. If your handling is slow, accept the request, respond, and process it asynchronously.
Return a 2xx status for success. Any 2xx counts as success. Everything else marks the block execution as failed. Redirects are followed as a standard HTTP client would, with the authentication headers set on the first request.
Be idempotent. Failed attempts are retried, so the same event can reach your endpoint more than once. Lobyco does not send an idempotency key today. Deduplicate on an identifier from the event payload, such as a receipt id or an activity id.
Expect UTF-8 JSON when a body is configured. The content type is application/json; charset=utf-8.

Retries and timeouts

Parameter	Default
Timeout per attempt	5,000 ms
Retries	2, so up to 3 attempts in total
Backoff	Jittered exponential, about 100 ms base

Lobyco retries transient failures only: HTTP 5xx, HTTP 408, network errors and timeouts. Other non-success statuses, such as 400, 401 and 404, are not retried and fail the block at once. The same policy applies to OAuth2 token requests. Lobyco can tune the defaults per environment.

What Lobyco records

For every execution Lobyco records the status code, the response body and the response time in the run details. Flow operators see this data when troubleshooting, so do not return 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 through DNS, to a private or link-local address. That covers 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 and Lobyco’s internal ranges. Lobyco checks this when the flow is saved and again at execution time, after placeholders are resolved.
Allowed methods are GET, POST, PUT, DELETE and PATCH.
The body content type is fixed at application/json; charset=utf-8. Form-urlencoded, XML and multipart cannot be configured, and a Content-Type custom header is ignored.
Secrets stay secret. OAuth2 client secrets, basic auth passwords and secret custom headers are encrypted at rest, and no Lobyco API or UI returns them in plain text.

Example setups

Each setup is the same short sequence. Create a credential in the external platform, create an integration in the Lobyco Admin Portal, and point the block at the endpoint.

Salesforce, with OAuth2 client credentials

In Salesforce, create a connected app with the client credentials flow enabled, and note the consumer key and secret.
In the Lobyco Admin Portal, create an Integration of type OAuth2 Client Credentials. The token URL is https://{your-domain}.my.salesforce.com/services/oauth2/token, the client ID is the consumer key, and the client secret is the consumer secret.
In the Outbound API block, reference the integration and configure the REST endpoint, for example POST https://{your-domain}.my.salesforce.com/services/data/v60.0/sobjects/Lead/. Build the JSON body from event and member placeholders.

Bloomreach, with basic auth

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 the API secret.
Create a Basic Auth integration with the API key id as the username and the API secret as the password.
Point the block at the endpoint, for example POST https://api.exponea.com/track/v2/projects/{projectToken}/customers/events.

Public-token endpoints, such as /track/v2/... and the consent fetch, also work with a Custom Headers integration carrying Authorization: Token <api_token>, marked secret. Private endpoints, such as /data/v2/... and /api/v2/..., require basic auth. Default to basic auth if your flow touches anything beyond tracking.

API-key platforms, with custom headers

For Iterable, Adobe or your own webhook receiver, create a Custom Headers integration with the vendor’s key header, such as Api-Key or X-Api-Key. Mark the value as secret and reference the integration from the block.

InboundAPI integration — the other direction, where your system starts a flow.
Events — the JSON Schemas of the event payloads the event placeholders draw on.
Block reference — what the marketer configures on the Outbound API block.

​At a glance

​When the block fires

​How a request is built

​Configuration

​Testing the block

​Placeholders

​Data sources

​Example body

​Supported Liquid features

​Authentication

​OAuth2 client credentials

​Basic auth

​Custom headers

​What your endpoint must do

​Retries and timeouts

​What Lobyco records

​Security and restrictions

​Example setups

​Salesforce, with OAuth2 client credentials

​Bloomreach, with basic auth

​API-key platforms, with custom headers

​Related

At a glance

When the block fires

How a request is built

Configuration

Testing the block

Placeholders

Data sources

Example body

Supported Liquid features

Authentication

OAuth2 client credentials

Basic auth

Custom headers

What your endpoint must do

Retries and timeouts

What Lobyco records

Security and restrictions

Example setups

Salesforce, with OAuth2 client credentials

Bloomreach, with basic auth

API-key platforms, with custom headers

Related