.agents/features/webhooks.md
Ingests inbound HTTP requests from external services and routes them to flows for execution. The module normalizes request payloads (handling multipart, binary, JSON, and text), supports both synchronous (blocking, waits for flow response) and asynchronous (fire-and-forget) execution modes, manages handshake verification for external services that challenge webhook ownership, and enforces payload size limits. It is the primary entry point for event-driven flow execution from outside Activepieces.
packages/server/api/src/app/webhooks/webhook.service.ts — core routing, sync/async execution, flow resolutionpackages/server/api/src/app/webhooks/webhook-controller.ts — 5 route registrations (sync, async, draft sync, draft async, test)packages/server/api/src/app/webhooks/webhook-request-converter.ts — payload normalization and file uploadpackages/server/api/src/app/webhooks/webhook-handshake.ts — handshake verification logicpackages/server/api/src/app/webhooks/webhook-module.ts — module registrationpackages/core/shared/src/lib/automation/webhook/dto.ts — WebhookUrlParams schemapackages/core/shared/src/lib/automation/trigger/index.ts — WebhookHandshakeStrategy enum and WebhookHandshakeConfiguration schemapackages/web/src/app/builder/test-step/custom-test-step/test-webhook-dialog.tsx — dialog for sending a manual test request to the webhook URLpackages/web/src/app/builder/test-step/test-trigger-section/manual-webhook-test-button.tsx — button that opens the test webhook dialogpackages/web/src/app/builder/test-step/test-trigger-section/index.tsx — test trigger panel (includes webhook test entry point)packages/components/icons/webhook.tsx — webhook icon used across the UICanonical term definitions live in the bounded-context glossaries — see CONTEXT-MAP.md.
/:flowId/sync) — blocks the HTTP connection until the flow completes and returns the flow's response payload/:flowId) — queues execution and returns 200 immediately with an x-webhook-id header/:flowId/test) — captures the request as sample data without executing the flowHEADER_PRESENT, QUERY_PRESENT, BODY_PARAM_PRESENT, NONE, HEAD_REQUEST (for services like Trello that validate by sending a HEAD request)publishedVersionId if set, falls back to latest draft| Route | Mode | Version | Purpose |
|---|---|---|---|
/:flowId/sync | SYNC | LOCKED_FALL_BACK_TO_LATEST | Production sync — blocks HTTP, returns flow response |
/:flowId | ASYNC | LOCKED_FALL_BACK_TO_LATEST | Production async — queues job, returns 200 immediately |
/:flowId/draft/sync | SYNC | LATEST | Testing sync — always uses draft version |
/:flowId/draft | ASYNC | LATEST | Testing async — draft version |
/:flowId/test | ASYNC | LATEST | Sample data only — no execution |
All routes accept GET, POST, PUT, DELETE, PATCH methods.
Async path:
AP_WEBHOOK_PAYLOAD_INLINE_THRESHOLD_KB (default 512KB). The job carries a JobPayload discriminated union — inline (value embedded) or ref (fileId of a WEBHOOK_PAYLOAD file).WorkerJobType.EXECUTE_WEBHOOK)x-webhook-id header immediatelyThe worker forwards the JobPayload straight into the EXECUTE_TRIGGER_HOOK engine operation; the engine resolves it at execution time (inline value, or a ref downloaded via the file-download path — direct bytes or an S3 signed-link redirect). Workers no longer fetch payloads themselves.
Sync path:
ProgressUpdateType.WEBHOOK_RESPONSEengineResponseWatcherAP_WEBHOOK_TIMEOUT_SECONDS, default 30; callers may pass timeoutMs to override per-invocation, e.g. MCP uses 5 minutes)webhookRequestConverter.convertRequest() normalizes incoming data:
rawBody for signature verification (non-binary only)x-parent-run-id, x-fail-parent-on-failure (for subflows)An inbound webhook POST can't be redirected to S3 (a third party already sent the body), so its bytes must transit the app — the only lever is to stop accumulating them. Webhook files stream straight to S3, reusing the write-path primitives (fileService.save({ data: Readable }), s3Helper.uploadStream, enforceByteLimit). See ADR-0008.
attachFieldsToBody is not registered globally — it is plugin-wide with no per-route opt-out, and its preValidation hook buffered every part of every multipart request. Each consumer now opts in instead:
request.parts();request.file();ApMultipartFile body via the per-route attachMultipartFieldsToBody hook (helper/multipart-body.ts).A new multipart route must pick one of these — there is no global request.body.<field> magic, and a route whose schema expects ApMultipartFile without the hook fails validation with 400 body/ Invalid input.
Stream both multipart/form-data parts and raw-binary bodies (image/*, pdf, zip, …) to S3; the flow payload keeps receiving a read-URL string.
DB fallback: stream to S3 only when FILE_STORAGE_LOCATION=S3; DB storage buffers to bytea as today.
Size guard: raw-binary bodies pipe through enforceByteLimit (MAX_FILE_SIZE_MB); multipart parts rely on busboy's limits.fileSize, which ends an oversized part cleanly and flags truncated rather than erroring it — so the converter fails the stream at end-of-stream, otherwise the truncated bytes are persisted before @fastify/multipart surfaces its 413.
rawBody / signature verification: config.rawBody is gone (via fastify-raw-body runFirst it buffered the entire body before parsing and defeated streaming). rawBody for the small signed types (JSON / XML / text) is captured in a scoped preParsing hook, where the raw string already exists. Streamed types (multipart, binary) forgo rawBody — binary already discarded it; multipart signature verification is dropped (accepted trade). See File Storage Service feature doc.
External services verify webhook ownership before sending events:
AP_MAX_WEBHOOK_PAYLOAD_SIZE_MB (default 5MB). Returns 413 if exceeded.
flowExecutionCache for fast lookuppublishedVersionId if exists, else latesthandshakeConfiguration, in which case the handshake is processed and the disabled check is skipped)