Webhooks in FMX Workflow Builder: Complete Setup Guide

Updated Today · 6 min readAdvanced

The Webhook workflow step sends FMX session information to an external HTTPS service. It can deliver guest details, survey answers, selections, session statistics, and supported media, then optionally wait for a response and reuse returned values later in the workflow.

Use Webhooks to connect FMX with a CRM, event activation, custom AI service, fulfillment system, lead database, or client-owned application.

Before going live: Have the receiving service developer provide the endpoint, authentication requirements, expected request fields, response example, timeout expectations, and maximum accepted payload size.

What a Webhook Can Send

The Builder can include supported combinations of:

Raw Photos
Final Photo
Final GIF
Raw Videos
Final Video
Signatures and AI Signatures
Scanned Hand/Palm Reading data on Windows
Survey Answers
Guest Emails and Phone Numbers
Selection Screen choices
Consent results
Session statistics
Custom fields created in the Webhook settings

Send only the data the receiving service actually needs.

1. Add and Position the Webhook

Add a Webhook Cloud step to the workflow.
Place it after every Survey, capture, AI, signature, or other step whose data must be included.
Place it after the selected media is produced.
Connect its success path to the next guest step.
Configure an error route when failure should lead to a recovery experience.

Node ordering matters. A Webhook cannot send a Final Photo, AI result, or survey answer that does not exist yet.

2. Configure the Request

URL

Enter the full HTTP or HTTPS endpoint. HTTPS is strongly recommended for any guest or event data.

Method

Choose POST or PUT to match the receiving service.

Headers

Add any required headers, such as an API key or content-type requirement. Header values can include supported workflow placeholders.

Do not expose a powerful administrative credential. Use a dedicated, limited key that can be rotated after the event.

Signing secret

When a signing secret is configured, FMX signs the request body and sends the signature in X-FMX-Signature. The receiving service should calculate the expected HMAC signature from the raw body and compare it before trusting the request.

3. Choose URL or Base64 Media

Gallery URL

Use Gallery URL when the receiver can download media from Foto Master Cloud.

Payloads stay much smaller than Base64.
The matching media must be enabled under Global Settings > Cloud.
FMX uses the available hosted or stable Cloud landing URL.
URL mode does not silently replace a missing URL with Base64 content.

The Cloud Sync preflight checks Gallery URL media before the booth starts.

Base64

Use Base64 when the receiving service must receive the media bytes directly and can accept a large JSON request.

Base64 uses the booth’s local media and does not require Cloud Sync for that media.
The request is significantly larger than the original file.
The configured inline-media limit is 10 MiB by default.
Base64 mode does not silently fall back to a hosted URL.

Large videos are usually better delivered as hosted URLs. Confirm server, proxy, and function payload limits before selecting Base64.

Guest signatures, AI signatures, and scanned-hand data are delivered as inline data where supported.

4. Add Custom Fields

Custom fields let you send fixed values and supported placeholders alongside FMX data. Typical examples include:

Client or campaign ID
Venue name
Booth number
Event code
Survey response
A value returned by an earlier Webhook

Use clear field names agreed with the receiving service. Do not include secrets in fields that could be logged or displayed later.

5. Fire-and-Forget Versus Wait for Response

Fire-and-forget

This is the default. FMX sends the request and continues through the normal workflow route without waiting for the external service to finish.

Use it when the guest experience should not pause for a CRM, analytics, or background automation request.

Fire-and-forget requests are not a durable offline queue and are not automatically retried by the Webhook node. The receiver should be reliable and idempotent.

Wait for response

Enable wait mode when the workflow needs returned data before it can continue.

Set the timeout from 1 to 300 seconds; 30 seconds is the default.
Any HTTP 2xx response is treated as success.
Network failures, timeouts, and non-2xx responses are treated as errors.
Use a loading animation before or around the wait so the guest understands that processing is in progress.

Keep guest-facing waits short. A service that may take several minutes should return a job reference quickly and finish asynchronously.

6. Define and Use Response Variables

When wait mode is enabled, paste a valid example of the expected JSON response into the Builder. The Builder uses it to expose the available paths for later fields.

Example response:

{
  "guest": {
    "firstName": "Alex"
  },
  "resultUrl": "https://example.com/result/123"
}

Later supported text fields can insert values such as the guest name or result URL from this Webhook. Use the Builder’s response-variable picker where available rather than typing a path manually.

Nested object properties and numeric array positions are supported. When a successful response is not JSON, the raw body is available through the response’s raw value.

7. Configure Error Routing

Error routing is available for wait-enabled Webhooks.

A recovery route can:

Show a friendly error animation
Offer a retry path
Continue without the external enhancement
Return to a Selection Screen
Preserve the locally produced Final Photo

If no error route is configured, FMX continues through the normal path after handling the failure. Configure an explicit route when the returned value is required for the next step.

Security and Privacy Checklist

Use HTTPS.
Use a dedicated least-privilege credential.
Configure and verify the request signature where possible.
Send only necessary guest data.
Obtain appropriate guest consent before sending personal information.
Avoid placing credentials in Custom fields or guest-visible responses.
Set receiver-side request and rate limits appropriate for event traffic.
Do not log complete Base64 media or sensitive headers.
Make the receiving endpoint idempotent so a controlled retry cannot create duplicate orders or records.

Test the Integration

Test with a staging endpoint before using production.
Run the exact workflow to produce all selected data and media.
Confirm headers and signature verification.
Confirm Gallery URL and Base64 requests independently if both are used.
Test the documented success response.
Test a non-2xx response, timeout, invalid JSON response, and network failure.
Confirm the error route and guest-facing message.
Repeat the test with a second session and check that data is not mixed between guests.
Review the receiving service for duplicate requests and payload-size failures.

Troubleshooting

The receiver gets no media

Place the Webhook after the media-producing step.
Confirm the selected media type exists in the current session.
For Gallery URL, enable the matching Cloud Sync media.
For Base64, check the inline size limit and receiver payload limit.

Gallery URL contains no usable file

URL mode never substitutes Base64. Confirm Cloud Sync, internet access, and the selected media type, then test the URL outside the Webhook receiver.

Base64 requests fail with “payload too large”

Use Gallery URL, reduce the media size, raise the receiver’s accepted request limit, or send fewer media items.

Response variables are unavailable

Enable wait mode, paste valid JSON into the response example, save the Webhook, and select the variable through the later field’s picker.

The guest is stuck on a loading screen

Set a reasonable timeout and configure an error route. Test how the receiver behaves when it is unavailable.

The same action happens twice

Make the receiver idempotent using a session or request identifier. Do not assume a network retry or operator retry can never occur.

For Cloud requirements, see Cloud Tab. For survey data, see How to Build Surveys.

Was this helpful?