HTTP endpoint functions (inbound webhooks)

HTTP endpoint functions receive calls from external systems — payment providers, e-signature callbacks, monitoring hooks, any service that pushes events to your workspace. Each endpoint is a C# class in the workspace Net Operation Project, authored in the NET Project mode of the Business Logic Development page (Constructor, group Automation & logic) using the Moltaro .NET SDK programming model.

Public route

Every enabled endpoint is served under one public inbound route:

GET|POST|PUT|PATCH|DELETE  /api/workspace/inbound/{endpointKey}/{**path}

endpointKey is the stable function key declared by [MoltaroFunction]. The optional [MoltaroHttpEndpoint] route adds path segments below the key, and whatever follows the key at call time reaches the handler as request.Path. Request bodies are capped by a platform size limit; calls to unknown or disabled endpoints fail with a plain-text error response.

Authoring shape

Derive from HttpEndpointFunction for raw, JSON, or form request data, or from HttpEndpointFunction<TBody> for a strongly typed JSON body, and override OnRequestAsync. The handler receives a MoltaroHttpRequest prepared by the runtime and returns a MoltaroHttpResponse. Request members:

• Method, EndpointKey, Path, ContentType;
• BodyBytes — the exact raw body bytes captured before parsing — and BodyText, the UTF-8 decoded text;
• JsonBody — the parsed JsonElement? for JSON endpoints without a typed body model; the typed variant exposes Body instead;
• Headers, Query, and Form value maps with the helpers GetHeader, GetHeaderValues, GetQuery, GetQueryValues, GetFormValue, and GetFormValues;
• Context — the function execution context, including CorrelationId.

Responses are built with the static factories MoltaroHttpResponse.Text, Json, Bytes, Empty, and Ok; each accepts a status code and optional extra response headers.

Endpoint declaration

[MoltaroHttpEndpoint] controls how the runtime accepts the call:

• Methods — MoltaroHttpMethodEnum flags (Get, Post, Put, Patch, Delete, All); defaults to Post.
• BodyMode — Json (default), Raw (exact body bytes and text), or FormUrlEncoded (form fields, no file uploads). Multipart is reserved for a future version and rejected by the build analyzers.
• AuthMode:
  • WorkspaceBearer (default) — workspace bearer tokens and service API keys;
  • Anonymous — no caller authentication; the endpoint runs as the service user configured in the endpoint settings, and only after an administrator explicitly enables it;
  • SharedSecretHeader — a managed endpoint secret passed in a request header (SharedSecretHeaderName, default X-Moltaro-Endpoint-Secret);
  • HmacSignature — a managed secret verified as an HMAC signature over the exact raw body (HmacSignatureHeaderName, default X-Moltaro-Signature), with replay protection from a Unix timestamp header (HmacTimestampHeaderName, default X-Moltaro-Signature-Timestamp) within HmacTimestampToleranceSeconds (default 300).
• ActorMode — AuthenticatedUser (default) runs as the authenticated caller; ConfiguredServiceUser runs as the service user set on the endpoint settings.

Enabling and administration

Discovered endpoints start disabled. An administrator enables them on the HTTP Endpoints page (Administration, group Monitoring) or through the admin API:

GET  /api/workspace/admin/http-endpoints
GET  /api/workspace/admin/http-endpoints/{endpointId}
PUT  /api/workspace/admin/http-endpoints/{endpointId}/settings
POST /api/workspace/admin/http-endpoints/{endpointId}/secrets

The settings operation owns the admin-side configuration; the secrets operation creates or rotates the managed endpoint secret and returns the plaintext exactly once. Settings updates and secret rotations are written to the audit log.

Run history

Every invocation attempt writes a run history entry, visible under Operations and diagnostics. Secrets and raw request bodies are redacted in run history. Callers can send an X-Moltaro-Correlation-Id header to correlate a call with its run.

Keep handlers short

An inbound endpoint should validate, record, and respond quickly. Move long work to a background job with IFunctionQueue.EnqueueAsync(functionKey, args, cancellationToken), which returns the queued job id — poll it with GET /api/workspace/functions/jobs/{jobId}.

The inbound handler itself is request-blocking even though OnRequestAsync returns Task; only the explicit queue call creates background work. The endpoint’s custom response and that queued job are separate lifecycles. See Asynchronous operations and polling for the execution-model rules.

Example

using System.Threading;
using System.Threading.Tasks;
using Moltaro.Package.NET;
using Moltaro.Package.NET.Functions;

namespace Moltaro.Operational.Functions.HttpEndpoints;

public sealed record PaymentEventBody
{
    public string? EventId { get; init; }

    public decimal Amount { get; init; }
}

[MoltaroFunction("payment-events", Name = "Payment events")]
[MoltaroHttpEndpoint(
    Methods = MoltaroHttpMethodEnum.Post,
    BodyMode = MoltaroHttpBodyModeEnum.Json,
    AuthMode = MoltaroHttpEndpointAuthModeEnum.HmacSignature,
    ActorMode = MoltaroHttpEndpointActorModeEnum.ConfiguredServiceUser)]
public sealed class PaymentEventsEndpoint(IFunctionQueue queue)
    : HttpEndpointFunction<PaymentEventBody>
{
    public override async Task<MoltaroHttpResponse> OnRequestAsync(
        MoltaroHttpRequest<PaymentEventBody> request,
        CancellationToken cancellationToken)
    {
        var jobId = await queue.EnqueueAsync(
            "process-payment-event",
            new { request.Body.EventId, request.Body.Amount },
            cancellationToken);

        return MoltaroHttpResponse.Json(new
        {
            accepted = true,
            jobId,
            correlationId = request.Context.CorrelationId
        });
    }
}

Once enabled, this endpoint answers POST /api/workspace/inbound/payment-events.

HTTP endpoint functions are inbound only. Moltaro has no outbound webhook publisher; outbound HTTP calls are made in C# from trigger functions or global functions.