ioLoop Docs

Appearance

Web Hooks ​

Web Hooks are Cloud Flow modules that receive HTTP requests, execute server-side logic, and return HTTP responses. Use them when a Page, custom frontend, external service, or other caller needs to invoke backend functionality through a request.

Web Hooks provide a request/response entry point into an ioLoop Project's backend. They can use the broader ioLoop Server APIs, Database, files, configured Connections, Flow Share helpers, and supported Node.js code to perform work that should not depend on the caller's browser.

A Web Hook is different from a Background Task. A Web Hook exposes an HTTP request endpoint; a Background Task is a backend module without that endpoint. For type selection, see Cloud Flow Types.

When to Use a Web Hook ​

Use a Web Hook when the caller needs to send a request to the Project backend, particularly for:

  • Validating and processing a Form submission that requires trusted business rules.
  • Checking record ownership, availability, eligibility, or other protected conditions.
  • Calling an external provider through a configured Connection.
  • Receiving notifications or callbacks from external systems.
  • Returning calculated, filtered, or otherwise processed results to a Page.
  • Performing server-only Database or file operations.
  • Providing an HTTP interface used by custom HTML/JavaScript or another system.

For example, an event registration Page can call a Web Hook to check available capacity, validate eligibility, create a registration, and return the outcome. The Page remains responsible for user interaction; the Web Hook owns the trusted processing.

Not every frontend action needs a Web Hook. Pages, Forms, Widgets, and custom JavaScript can use supported ioLoop Client APIs directly for operations permitted by the current user's access rules. Use a Web Hook when an HTTP backend entry point, trusted execution, or server-only capability is needed.

How Web Hooks Work ​

A typical Web Hook request follows this sequence:

  1. A caller sends an HTTP request to the Web Hook URL using the configured method.
  2. The Web Hook's configured access rules determine whether the caller may invoke it.
  3. Cloud Flow reads the available request data, parameters, and headers.
  4. The workflow validates inputs, authenticates or verifies the caller where necessary, and checks business rules.
  5. The workflow performs the intended server-side operation.
  6. The Web Hook sets an appropriate response status, content, and any required headers, then finishes the request.
  7. The caller handles the response or error.
text
Page Flow, custom frontend, or external service
                    |
                    | HTTP request
                    v
              Cloud Flow Web Hook
               Read request data
               Validate and authorize
               Run backend operations
               Prepare HTTP response
                    |
                    v
             Caller handles result

This is a conceptual workflow, not a specific Cloud Flow block sequence. The actual implementation depends on the Web Hook's configuration and the blocks or custom code used.

Creating a Web Hook ​

To create one in the Project Editor:

  1. Open Backend → Cloud Flow.
  2. Choose New Cloud Flow → Web Hook.
  3. Enter a clear Web Hook Name.
  4. Select the appropriate Hook HTTP Method.
  5. Configure Response Streaming if the request requires a supported streaming behavior.
  6. Save the module.
  7. Select Edit Flow and implement its request, processing, and response logic.
  8. Configure Access (Security) for the intended callers.
  9. Save the flow and test it using the provided development endpoint.

The module is created and configured in the Cloud Flow list; its executable logic is built in the Cloud Flow Editor.

For module actions such as Enable/Disable, Clone, Delete, and Load Order, see Managing Cloud Flow.

Web Hook Settings ​

The Settings action exposes the Web Hook-specific configuration.

SettingPurpose
NameIdentifies the Web Hook and forms part of its URL.
Hook HTTP MethodSpecifies the HTTP method the endpoint accepts, such as GET or POST.
Response StreamingSelects the supported response delivery behavior for the endpoint.

Access (Security) and Enable/Disable are separate module actions rather than settings in this dialog.

Name and URL ​

Choose a stable name that describes the operation, such as CreateRegistration, GetOrderSummary, or ReceiveProviderEvent.

The settings panel shows the development test URL and the published URL pattern for the current Web Hook. Use the URLs shown by ioLoop; do not construct endpoint URLs from guessed naming rules.

Changing the Web Hook name changes the URL used by callers. After renaming, update any Page Flow calls, custom frontend code, external service callbacks, and other saved references that depend on the old endpoint.

Hook HTTP Method ​

Select a method appropriate for how the caller sends information.

MethodTypical Use
GETRead-oriented requests using suitable query parameters.
POSTSubmitting request bodies for processing or operations that may change data.

Use the method actually supported and selected in the Web Hook settings. A caller using the wrong method may not reach the intended workflow. Avoid placing sensitive credentials in query strings.

Response Streaming ​

Response Streaming determines how the endpoint delivers response content where the selected behavior is supported. The available configurations include ordinary non-streamed responses and supported piped pass-through or chunked response streaming modes.

Use a normal response when the caller expects one completed result, such as a registration confirmation or a JSON result. Consider streaming only when the backend processing and receiving client are intentionally designed to work with incremental or pass-through output.

Selecting a streaming mode does not by itself design the stream-producing logic. The implementation must use the appropriate supported Cloud Flow or Server API behavior, and the caller must be able to consume that response mode.

For streaming workflows, test the full response with the actual caller, including completion and failure after a response has begun. See Node.js Runtime and SDK Libraries for related server-side programming concepts.

Reading Incoming Requests ​

Cloud Flow provides dedicated blocks for accessing parts of an incoming Web Hook request.

BlockInformation Provided
Request DataThe request body data available to the Web Hook.
Request ParamsQuery-string parameters.
Request HeadersIncoming HTTP headers.
Request IP AddressThe client IP address exposed by the request context.

Use request body data for structured values submitted by the caller, such as a registration or order request. Use query parameters for appropriate URL-supplied values and headers for supported protocol or authentication information.

For example, a registration request might provide:

json
{
  "eventId": "event-123",
  "attendeeName": "Asha Patel",
  "attendeeEmail": "[email protected]"
}

This JSON is an illustrative request body, not a required ioLoop schema. Define and validate the actual fields needed by your Web Hook.

Validate Request Inputs ​

Treat all request data as untrusted, even when it comes from one of the Project's own Pages.

Check the values the operation actually requires:

  • Are mandatory fields present and in the expected format?
  • Are record IDs valid and associated with the intended records?
  • Is the requested operation allowed for the current record state?
  • Does the caller have permission to act on the requested data?
  • Are user identity, group membership, or ownership claims verified from trustworthy context rather than accepted from the request body?

Request headers, query parameters, and IP information can assist with request handling, but the workflow should not treat an arbitrary value as proof of identity or authorization. Use a supported authentication method, such as a Project User Web Hook Key, or validate the external provider's required signature or credential according to its contract.

For the broader security model, see Access Security.

Building the Response ​

A Web Hook can return structured data, text, a redirect, or other supported HTTP output. Its response should match the caller's expected contract.

The Cloud Flow block reference includes these response controls:

BlockPurpose
Response: Send with DataSets response-body data without immediately ending the flow.
Set Response StatusSets the HTTP status code.
Set Response Content-TypeSets the response content type.
Response: Set value of HeaderSets an HTTP response header.
Response: Send RedirectSends a redirect to a supplied URL or path.
Webhook: Exit (Success)Finishes the Web Hook successfully.
Webhook: Exit with errorFinishes the Web Hook with a failure result and an error message.

Setting response data and finishing the Web Hook are distinct actions in the block model. In particular, Response: Send with Data allows subsequent blocks to set response headers, status, or content type before the flow exits. Use the appropriate exit or completion behavior for the implementation rather than assuming that setting the body ends processing.

Response Status and Content Type ​

Use the HTTP status to communicate the request outcome and a content type appropriate to the returned body. For example, a successful operation may return JSON, while a validation or authorization failure should communicate a failure that the caller can recognize.

A caller should not have to infer success from arbitrary text. Define predictable success and failure handling, and do not expose stack traces, private credentials, or internal system information in user-facing errors.

For a streaming response, set any required status and response headers before streaming begins. Once response data has started, do not rely on changing the status, content type, or headers.

Piped Pass-Through Responses ​

Use a piped response when the Web Hook should pass a Node.js readable stream directly to the caller, such as a file download or a streamed response produced by an SDK.

Before using this response mode, set Response Streaming in the Web Hook settings to Piped (Pass-through). Then call:

js
$io.system.pipeWebHookResponse(
  $ioHookCtxt,
  readableStream,
  'application/octet-stream',
  false,
  function (eventType) {
    if (eventType === 'error') {
      $io.system.log('Piped Web Hook response failed', 'WEBHOOK', 1);
    }
  }
);

In this example, readableStream represents a Node.js readable stream obtained or created by the Cloud Flow logic. The content type should describe the data being streamed.

The arguments are:

ArgumentPurpose
$ioHookCtxtThe current Web Hook context available to the flow.
readableStreamThe Node.js readable stream to send to the caller.
contentTypeThe response content type, such as application/pdf, application/octet-stream, or text/plain.
noAutoExitWhen false, ioLoop completes the Web Hook flow when the stream ends, closes, or fails. When true, the callback must explicitly finish the flow.
endCbFnReceives the stream completion event and can perform final flow handling.

For the usual case, set noAutoExit to false. If the flow requires explicit completion handling, set it to true and call $io.system.exitWebHook from the callback:

js
let flowFinished = false;

$io.system.pipeWebHookResponse(
  $ioHookCtxt,
  readableStream,
  'text/plain; charset=utf-8',
  true,
  function (eventType) {
    if (flowFinished) {
      return;
    }

    flowFinished = true;
    const succeeded = eventType !== 'error';
    $io.system.exitWebHook($ioHookCtxt, succeeded, succeeded ? '' : 'Response stream failed');
  }
);

Do not also build a normal response body or use a normal Web Hook exit path while the piped response owns the response. Handle stream errors, and test cancellation or early closure with the actual caller.

Chunked Responses ​

Use a chunked response when Cloud Flow produces response data incrementally and needs to send each piece as it becomes available.

Before using this response mode, set Response Streaming in the Web Hook settings to Chunked. A chunked response has a required lifecycle:

  1. Call $io.system.chunkWebHookResponseStart once.
  2. Call $io.system.chunkWebHookResponseAdd for each non-empty piece of data.
  3. Call $io.system.chunkWebHookResponseEnd once after the final piece.

For example, a Web Hook can return newline-delimited JSON records:

js
$io.system.chunkWebHookResponseStart(
  $ioHookCtxt,
  'application/x-ndjson; charset=utf-8'
);

$io.system.chunkWebHookResponseAdd(
  $ioHookCtxt,
  JSON.stringify({ stage: 'started' }) + '\n'
);

$io.system.chunkWebHookResponseAdd(
  $ioHookCtxt,
  JSON.stringify({ stage: 'complete', count: 24 }) + '\n'
);

$io.system.chunkWebHookResponseEnd(
  $ioHookCtxt,
  false,
  function () {
    $io.system.log('Chunked Web Hook response completed', 'WEBHOOK', 0);
  }
);

chunkWebHookResponseAdd sends response data as supplied. Use non-empty strings or supported binary data. Serialize JavaScript objects explicitly, and choose a framing format the caller understands. For example, newline-delimited JSON places one serialized object on each line; ordinary JSON does not become a valid incremental format merely by splitting it into arbitrary pieces.

As with piped responses, setting noAutoExit to false on $io.system.chunkWebHookResponseEnd completes the Web Hook flow automatically. Set it to true only when the completion callback will explicitly call $io.system.exitWebHook:

js
$io.system.chunkWebHookResponseEnd(
  $ioHookCtxt,
  true,
  function () {
    $io.system.exitWebHook($ioHookCtxt, true, '');
  }
);

Always end a started chunked response, including when processing fails after streaming has begun. At that point, the response may already have been partially delivered, so send a format-appropriate final error item when possible and then end the response. Do not attempt to replace it with a separate normal response.

For exact signatures and parameters, see $io.system.pipeWebHookResponse, $io.system.chunkWebHookResponseStart, $io.system.chunkWebHookResponseAdd, and $io.system.chunkWebHookResponseEnd.

Result Objects and HTTP Responses ​

ioLoop Result Objects use fields such as status, data, and err to represent application-level results. These are useful for expressing an operation's outcome.

An HTTP response, however, also has its own status code, headers, content type, and body. These are related but not interchangeable concepts. A successful HTTP transport does not necessarily mean the requested business operation succeeded.

For instance, a Page calling a registration Web Hook should check the operation result it receives and display the appropriate confirmation or failure message rather than assuming every completed request created a registration.

For exact block behavior, see HTTP and Web Hooks Blocks and Result Objects.

Calling Web Hooks from Pages ​

Page Flow can invoke a Cloud Flow Web Hook through supported blocks. Custom frontend JavaScript can also use the corresponding supported ioLoop Client APIs or HTTP interactions where appropriate.

A typical Page interaction is:

  1. The user submits a Form or selects an action.
  2. The frontend gathers the required input and can provide immediate validation feedback.
  3. The frontend invokes the Web Hook.
  4. The Web Hook validates and processes the request.
  5. The frontend handles success or failure after the call completes.
  6. On success, the Page updates the relevant content, Data Table, or workflow state.

Built-in Forms, Widgets, and Page Flow blocks are higher-level ways of using ioLoop Client API capabilities. A fully custom frontend can implement equivalent user experiences using the supported Client APIs. The Web Hook and its server-side permissions do not change based on which frontend approach is used.

For detailed Page Flow coordination and invocation patterns, see Calling Cloud Flow from Pages.

Calling Web Hooks from External Systems ​

An external service can use the published Web Hook endpoint when its method, access configuration, and request/response handling meet the integration's requirements.

Typical uses include receiving an event from a service, accepting an integration callback, or exposing a narrow API operation.

Calling as a Project User ​

An external application can authenticate as a Project User by sending that user's Web Hook Key in the HTTP Authorization header with the Bearer scheme:

http
Authorization: Bearer PROJECT_USER_WEB_HOOK_KEY

For example:

bash
curl --request POST "WEB_HOOK_URL" \
  --header "Authorization: Bearer PROJECT_USER_WEB_HOOK_KEY" \
  --header "Content-Type: application/json" \
  --data '{"orderId":"order-123"}'

Replace WEB_HOOK_URL with the development or published URL displayed for the Web Hook, and replace PROJECT_USER_WEB_HOOK_KEY with the key generated for the intended Project User.

The associated Project User must be active and permitted by the Web Hook's Access (Security) configuration. Access is evaluated using the user's group memberships, role levels, and applicable Admin access. A valid key identifies the caller; it does not bypass Web Hook access rules or authorize every operation the caller might request.

The Cloud Flow must still enforce record ownership, permitted actions, business rules, and other operation-specific authorization. For example, a user who may invoke an order Web Hook is not automatically permitted to update every order.

Treat a Web Hook Key like a password:

  • Send it only over HTTPS.
  • Keep it in the calling application's secret or credential storage.
  • Do not place it in a URL or query string.
  • Do not embed it in Page Flow, frontend JavaScript, HTML, or another browser-delivered asset.
  • Do not write it to Cloud Flow logs or other diagnostic output.
  • Replace it when exposure is suspected, then verify that the previous key is no longer accepted.

Create and manage Web Hook Keys under Settings → Users. For details, see Users — Web Hook Keys.

Project User authentication is different from authenticating a provider callback. When a payment provider or another external service supplies its own signature or verification mechanism, follow that provider's requirements rather than substituting an unrelated Project User key.

Before connecting an external caller:

  1. Identify the expected HTTP method and payload structure.
  2. Configure the Web Hook's Access (Security) according to the caller.
  3. Determine how the caller will prove authenticity, where required.
  4. Validate incoming values and protect against duplicate delivery.
  5. Decide which HTTP status, body, or acknowledgement the caller expects.
  6. Test with a realistic request before pointing a live provider at the published URL.

External services may retry delivery when requests fail or responses are delayed. Where the operation can change state, use an appropriate idempotency or duplicate-detection strategy rather than assuming each event is delivered exactly once.

Do not make a Web Hook public solely for convenience. An unlisted URL is not a security control.

Access and Security ​

Web Hooks are trusted backend entry points, but running on the server does not automatically make every request authorized.

Use two complementary layers:

LayerResponsibility
Web Hook Access (Security)Determines which callers may invoke the endpoint according to its configured access model.
Workflow authorization and validationDetermines whether a permitted caller may perform this specific operation on the requested data.

For protected workflows:

  • Verify the caller or Project User identity where applicable.
  • Enforce ownership, User Group, record-status, and other relevant business rules on the backend.
  • Use configured Connections for external credentials rather than accepting secrets from frontend code.
  • Return only the information the caller is entitled to receive.
  • Avoid exposing private Database or file data through broad response objects.
  • Apply appropriate safeguards for public endpoints, repeated requests, and potentially expensive operations.

When an external caller uses a Project User Web Hook Key, ioLoop evaluates the request as that user. The Web Hook's Access (Security) rules still determine whether the user may invoke it, and the workflow remains responsible for authorizing the requested operation.

Page Access, hidden Buttons, or client-side validation alone cannot secure a Web Hook. A caller may attempt to invoke the endpoint independently of the Page that normally uses it.

See Access Security for detailed authorization guidance.

Practical Example: Registration Web Hook ​

Consider a public event Page that collects registration details and needs to enforce capacity limits.

1. Configure the Web Hook ​

Create a Web Hook named CreateRegistration using the appropriate HTTP method and access setting. Review its development and published URLs. Set up the intended request and response format.

2. Implement Processing ​

A conceptual Cloud Flow sequence is:

text
Read registration request
  Validate required attendee and event values
  Retrieve event and current registration state
  Check whether registration is allowed
  If not allowed:
    Set appropriate failure response
    Finish Web Hook
  Otherwise:
    Create registration through trusted Database logic
    Set success response with permitted result data
    Finish Web Hook

This diagram is illustrative, not an exact block sequence. If concurrent registrations could exceed event capacity, the backend design must account for that concurrency; checking capacity and later creating a record should not be assumed to be an atomic operation automatically.

3. Connect the Frontend ​

Have the Page or Form call CreateRegistration with the necessary values. When the operation succeeds, show confirmation and update the displayed availability. When it fails, display a clear message without claiming that a registration was created.

4. Test and Publish ​

Test accepted registrations, full events, invalid inputs, repeated submissions, unauthorized requests, and failures during Database processing. Publish only after validating the intended outcomes and then verify the released endpoint and caller behavior.

Development, Testing, and Publishing ​

The Project Editor provides development test URLs for Web Hooks separately from their published URL patterns. Use the displayed development endpoint for testing changes before publication.

During Preview, built-in Database operations automatically use the Project's development database. Test the actual Web Hook and Database operations in their intended development runtime context. Do not assume that external providers or manually configured requests automatically switch to test mode.

When testing Web Hooks:

CaseWhat to Verify
Valid requestThe Web Hook performs the intended operation and returns the expected result.
Missing or invalid inputValidation fails safely and returns understandable feedback.
Unauthorized callerThe endpoint or workflow rejects the operation and does not modify protected data.
Empty or missing recordThe workflow handles absent Database results correctly.
External service failureThe caller receives an appropriate failure and credentials are not exposed.
Duplicate requestRepeated submissions do not create unintended duplicate effects.
Response contractHTTP method, status, headers, body, and completion match the caller's expectations.
Streaming modeThe actual caller handles response chunks or pass-through output correctly where configured.
Published endpointThe correct published URL and access settings work after release.

Use Start Test, Stop Test, and Logs from the Cloud Flow area where appropriate. Logs distinguish test and live activity and are valuable for investigating backend failures that do not appear directly in Page Flow.

For a complete testing and logging workflow, see Testing and Logs.

Troubleshooting ​

ProblemWhat to Check
Web Hook cannot be reachedDevelopment versus published URL, method, enabled state, access settings, and whether the intended runtime is available.
Request data is missingActual request payload, content type, body versus query parameters, and caller configuration.
Request is deniedWeb Hook Access (Security), user/caller identity, required authentication, and workflow authorization.
Wrong result or incomplete responseResponse data, content type, HTTP status, headers, and Web Hook exit behavior.
Page does not updateThe frontend's response handling, asynchronous completion, and Page Flow success/error branches.
External provider keeps retryingExpected acknowledgement, response status, processing time, and duplicate-event handling.
Streaming output failsStreaming setting, server-side stream handling, response completion, and caller support.
Works in test but not after publishURL, published version, production data and Connections, access configuration, and live logs.

When investigating an issue, start with a known request and inspect both the caller's result and the Cloud Flow logs. This helps distinguish endpoint configuration, validation, backend processing, and response handling problems.

Good Practices ​

  • Choose the endpoint contract first. Define the method, required inputs, access model, and response expected by callers.
  • Keep names and URLs stable. Treat changes to a Web Hook used by other components as a compatibility change.
  • Validate every request. Browser-provided and external data are untrusted until checked.
  • Enforce business rules on the server. Web Hook access alone is not record-specific authorization.
  • Use consistent responses. Keep HTTP and application-level status meaningful to callers.
  • Use Connections for credentials. Avoid putting protected tokens in frontend code or request bodies.
  • Handle repeated requests. Prevent unintended duplicate changes when callers retry.
  • Keep returned data minimal. Avoid exposing unnecessary records or internal error details.
  • Test the complete caller path. Include development, published, success, failure, and security cases.

Common Mistakes ​

Avoid these patterns:

  • Making a Web Hook public simply because it is easier to test.
  • Assuming an unknown or hard-to-guess URL makes the endpoint secure.
  • Trusting client-supplied user IDs, group names, prices, or record ownership without verification.
  • Using the wrong HTTP method or a stale URL after renaming.
  • Assuming that setting response data automatically finishes the Web Hook.
  • Treating a successful HTTP exchange as proof that the business operation succeeded.
  • Returning sensitive Database fields when the caller only needs a short result.
  • Ignoring external retries, concurrency, or duplicate events.
  • Enabling streaming without designing and testing the stream lifecycle.
  • Testing only from Cloud Flow and not from the actual Page or external service.
  • Confusing the development test endpoint with the published endpoint.

Web Hooks work best as well-defined backend interfaces: clear requests, explicit authorization, carefully controlled operations, predictable responses, and testing through the real caller.

Technical Reference ​